Export DOCX via REST API

Available in Start planBetav2.8.0

The DOCX export API converts Tiptap JSON documents into .docx (Microsoft Word) files.

Review the postman collection

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

Export DOCX

POST /v2/convert/export/docx

The /v2/convert/export/docx 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/docx 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/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"attrs\":{\"textAlign\":\"left\"},\"content\":[{\"type\":\"text\",\"text\":\"Welcome to this demonstration of our editor ability to export a wide array of formatting options to DOCX, ensuring that your content retains its intended appearance in Word.\"}]}]}",
      "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 Convert settings page: https://cloud.tiptap.dev/v2/cloud/convert
`Content-Type`	Must be `application/json`

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/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Document with custom page size\"}]}]}",
      "exportType": "blob",
      "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/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Document with custom margins\"}]}]}",
      "exportType": "blob",
      "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.

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
`differentFirstPage`	`boolean`	Whether to use a different header on the first page. When `true`, the `first` value is used on page one instead of `default`.
`default`	`string`	The standard default header on every page, or header on odd pages when the `evenAndOddHeaders` option is activated. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting.
`first`	`string`	The header on the first page. Only used when `differentFirstPage` is set to `true`. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting.
`even`	`string`	The header on even pages when the `evenAndOddHeaders` option is activated. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting.

Plain text vs. Tiptap JSONContent

Each header value can be either a plain text string (produces a simple unstyled header) or a stringified Tiptap JSONContent object (enables rich formatting such as bold, italic, links, etc.). When passing JSONContent, stringify the object with JSON.stringify() before sending it in the request body.

Example cURL with custom headers:

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Document with custom headers\"}]}]}",
      "exportType": "blob",
      "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
`differentFirstPage`	`boolean`	Whether to use a different footer on the first page. When `true`, the `first` value is used on page one instead of `default`.
`default`	`string`	The standard default footer on every page, or footer on odd pages when the `evenAndOddFooters` option is activated. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting.
`first`	`string`	The footer on the first page. Only used when `differentFirstPage` is set to `true`. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting.
`even`	`string`	The footer on even pages when the `evenAndOddFooters` option is activated. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting.

Plain text vs. Tiptap JSONContent

Each footer value can be either a plain text string (produces a simple unstyled footer) or a stringified Tiptap JSONContent object (enables rich formatting such as bold, italic, links, etc.). When passing JSONContent, stringify the object with JSON.stringify() before sending it in the request body.

Example cURL with custom footers:

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Document with custom footers\"}]}]}",
      "exportType": "blob",
      "footers": {"evenAndOddFooters": true, "default": "Default Footer", "first": "First Page Footer", "even": "Even Page Footer"}
    }'

Response

On success the API returns the DOCX file as a binary download:

Status: 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename=export-{timestamp}.docx

Error responses

Status	Code	Description
400	`NO_DOCUMENT_PROVIDED`	No document was provided in the body
422	`FAILED_TO_PARSE_DOCX_FILE`	Failed to parse JSON inputs
422	`FAILED_TO_EXPORT_DOCX_FILE`	Failed to export DOCX
422	`FAILED_TO_CONVERT_DOCX_TO_BLOB`	Failed to convert result type

PreviouslyExport styles

Next upPDF