--- title: "Export DOCX via REST API" description: "Learn how to export Tiptap JSON documents to DOCX format via the Conversion REST API." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/rest-api" --- # Export DOCX via REST API Learn how to export Tiptap JSON documents to DOCX format via the Conversion REST API. - **1. Activate trial or subscribe** Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start plan](https://cloud.tiptap.dev/v2/billing) in your account. - **2. Configure Convert app** Authenticate REST calls with a signed token carrying `aud: "Convert"`. See [Authentication](https://tiptap-docs.lin52025i.qzz.io/authentication.md). The DOCX export API converts Tiptap JSON documents into `.docx` (Microsoft Word) files. It uses the same conversion library as the [editor extension](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/editor-extension.md) and produces equivalent DOCX output for standard content. The REST API supports [style overrides](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/styles.md), [custom-node rendering via the DSL](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/custom-nodes-dsl.md), page size and margins, headers/footers, comment threads, and element-level overrides (`tableOverrides`, `paragraphOverrides`, `textRunOverrides`, `tableCellOverrides`, `imageOverrides`). It does not accept JavaScript-function options. For the function-based custom-node API, use the [editor extension](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/editor-extension.md), which also works server-side. > **Review the postman collection:** > > You can also experiment with the Document Conversion API by heading over to our [Postman > Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-bcc93ecb-8bad-4484-8cb0-d995ee23ae60). ## 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 accepts [style overrides](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/styles.md), > page size/margins, headers/footers, the five element-level overrides (`tableOverrides`, > `paragraphOverrides`, `textRunOverrides`, `tableCellOverrides`, `imageOverrides`), and > [custom-node rendering via the JSON DSL](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/custom-nodes-dsl.md). It does not > accept JavaScript-function options. For the function-based custom-node API, use the [editor > extension](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/editor-extension.md) or the [server side export > guide](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/editor-extension.md#server-side-export). ### Example (cURL) ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -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](https://tiptap.dev/pricing). ### Required headers | Name | Description | | --------------- | --------------------------------------------------------------------------- | | `Authorization` | The JWT token to authenticate the request. Example: `Bearer your-jwt-token` | | `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` | | `tableOverrides` | `Object` | Table-level rendering overrides | `undefined` | | `paragraphOverrides` | `Object` | Paragraph-level rendering overrides | `undefined` | | `textRunOverrides` | `Object` | Text run rendering overrides | `undefined` | | `tableCellOverrides` | `Object` | Table cell rendering overrides | `undefined` | | `imageOverrides` | `Object` | Image rendering overrides | `undefined` | | `headerFooterOverrides` | `Object` | Per-field overrides scoped to header/footer content (same five keys as the element overrides). See [Element Overrides](#element-overrides). | `undefined` | | `customNodeDsl` | `Object` | [Custom-node DSL](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/custom-nodes-dsl.md) rules | `undefined` | | `placeholders` | `Object \| false` | Optional `{ page?, total? }` rename map matching `Pages.configure({ placeholders })` so renamed tokens (e.g. `{p}` / `{pages}`) in each header or footer slot become live `PAGE` / `NUMPAGES` fields. Pass `false` to disable substitution entirely (literal `{page}` / `{total}` text in the exported `.docx`). See [Custom token names](#custom-token-names-placeholders). | `undefined` | | `comments` | `Object` | Comment threads to embed as native Word comments: `{ threads: [...] }`. Each thread carries its messages, author, dates, and resolved state, and is anchored to the document's `inlineThread` / `blockThread` marks. See [Comments](#comments). | `undefined` | | `footnotes` | `Object` | Footnote bodies keyed by note id. Each value is a Tiptap JSON document. See [Footnotes and endnotes](#footnotes-and-endnotes). | `undefined` | | `endnotes` | `Object` | Endnote bodies keyed by note id, in the same shape as `footnotes`. See [Footnotes and endnotes](#footnotes-and-endnotes). | `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:** ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -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:** ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -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 \| Object` | The standard default header on every page, or header on odd pages when the `evenAndOddHeaders` option is activated. Accepts plain text, stringified Tiptap JSONContent, or a Tiptap JSONContent object. | | `first` | `string \| Object` | The header on the first page. Only used when `differentFirstPage` is set to `true`. Accepts plain text, stringified Tiptap JSONContent, or a Tiptap JSONContent object. | | `even` | `string \| Object` | The header on even pages when the `evenAndOddHeaders` option is activated. Accepts plain text, stringified Tiptap JSONContent, or a Tiptap JSONContent object. | > **Accepted slot values:** > > Each header value may be one of three shapes: > > - A **plain text string.** Produces a simple unstyled header. > - A **stringified Tiptap JSONContent.** Enables rich formatting such as bold, italic, and links. Produce it with `JSON.stringify(yourHeaderDoc)`. > - A **Tiptap JSONContent object.** The same rich content, sent as a nested JSON object inside the request body without stringifying it. > > In a JSON request body, an object must include a `type` field, and an invalid shape returns `400 Bad Request`. **Example cURL with custom headers:** ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -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 \| Object` | The standard default footer on every page, or footer on odd pages when the `evenAndOddFooters` option is activated. Accepts plain text, stringified Tiptap JSONContent, or a Tiptap JSONContent object. | | `first` | `string \| Object` | The footer on the first page. Only used when `differentFirstPage` is set to `true`. Accepts plain text, stringified Tiptap JSONContent, or a Tiptap JSONContent object. | | `even` | `string \| Object` | The footer on even pages when the `evenAndOddFooters` option is activated. Accepts plain text, stringified Tiptap JSONContent, or a Tiptap JSONContent object. | > **Accepted slot values:** > > Each footer value may be one of the same three shapes as a header value: a plain text string, a > stringified Tiptap JSONContent, or a Tiptap JSONContent object. In a JSON request body, an object > must include a `type` field, and an invalid shape returns `400 Bad Request`. > **\`\{page}\` / \`\{total}\` tokens become live Word fields:** > > The REST API translates `{page}`, `{total}`, and the `{numpages}` synonym inside headers/footers > into live Word `PAGE` / `NUMPAGES` fields in the exported `.docx`. This works in every slot shape: > a plain text string, stringified Tiptap JSON, or a Tiptap JSON object. Custom token names such as > `{p}` / `{pages}` require passing the optional `placeholders` rename map. See [Custom token > names](#custom-token-names-placeholders) below. Pass `"placeholders": false` to ship the tokens as > literal text instead. #### Custom token names (`placeholders`) When the editor renames the built-in tokens via [`Pages.configure({ placeholders })`](https://tiptap-docs.lin52025i.qzz.io/pages/core-concepts/page-header-footer.md#renaming-or-disabling-placeholders), forward the same rename map to the REST API so the wire format stays aligned. The wire field has the same name and shape as the editor option: ```json { "doc": "{\"type\":\"doc\",\"content\":[]}", "footers": { "default": "{p} of {pages}" }, "placeholders": { "page": "p", "total": "pages" } } ``` When the map is omitted, the service falls back to recognizing `{page}`, `{total}`, and `{numpages}` (Word's spelling for the total-pages field, kept as a synonym so direct REST API callers can mirror what `/import/docx` emits). Renaming `total` removes the `{numpages}` synonym so stale tokens render literally; the rename is strict. Pass `"placeholders": false` to disable substitution on every slot so all `{page}` / `{total}` text ships literally with no live fields. **Example cURL with custom footers:** ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -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"} }' ``` ### Comments Pass a `comments` object to embed comment threads as native Word comments in the exported `.docx`. Each thread is anchored to the text it belongs to through the document's own comment markers: an `inlineThread` mark whose `data-thread-id` matches the thread `id`, or a `blockThread` node. The `comments` field supplies the thread bodies, authors, dates, and resolved state. The shape mirrors the editor's export extension: | Field | Type | Description | | ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `threads` | `Array` | The comment threads to embed. | | `threads[].id` | `String` | Thread id. Must match the `data-thread-id` on the matching `inlineThread` / `blockThread` in `doc`. | | `threads[].resolvedAt` | `String \| null` | When set, the thread is exported as resolved. | | `threads[].comments` | `Array` | The thread's messages, root first, then replies in order. | | `comments[].id` | `String` | Message id. | | `comments[].content` | `String \| Object` | The message body as plain text or Tiptap JSON. | | `comments[].data` | `Object` | Optional metadata: `author`, `initials`, `dateIso`, `dateUtc`, and round-trip identities (`originalWId`, `originalDurableId`). | When omitted, the export contains no comments, so existing requests are unaffected. **Example cURL with a comment thread:** ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Reviewed text\",\"marks\":[{\"type\":\"inlineThread\",\"attrs\":{\"data-thread-id\":\"T1\"}}]}]}]}", "exportType": "blob", "comments": { "threads": [ { "id": "T1", "resolvedAt": null, "comments": [ { "id": "c1", "content": "Please cite a source.", "data": { "author": "Ada Lovelace", "initials": "AL", "dateIso": "2026-01-01T00:00:00.000Z" } } ] } ] } }' ``` ### Footnotes and endnotes Pass `footnotes` and `endnotes` to export Word footnotes and endnotes. Each is an object keyed by note id, and each value is a Tiptap JSON document with `"type": "doc"`. A `footnoteReference` or `endnoteReference` node in `doc` becomes a Word note when its `noteId` attribute has an entry in the matching object. The export leaves out references without an entry. A value that is not a Tiptap JSON document returns `400 Bad Request`. The shape matches the `footnotes` and `endnotes` fields that the [DOCX import](https://tiptap-docs.lin52025i.qzz.io/conversion/import/docx/rest-api.md) returns. In a `multipart/form-data` request, send each field as a JSON string. **Example cURL with a footnote:** ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Body text\"},{\"type\":\"footnoteReference\",\"attrs\":{\"noteId\":\"1\"}}]}]}", "footnotes": { "1": { "type": "doc", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "A footnote." }] }] } } }' ``` ### Element Overrides #### Example cURL combining multiple element overrides ```bash curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Doc with element-level overrides\"}]}]}", "tableOverrides": { "borders": { "top": { "style": "none" }, "bottom": { "style": "none" }, "left": { "style": "none" }, "right": { "style": "none" }, "insideHorizontal": { "style": "none" }, "insideVertical": { "style": "none" } } }, "paragraphOverrides": { "spacing": { "before": 200, "after": 200 } }, "textRunOverrides": { "font": "Arial", "size": 24 }, "tableCellOverrides": { "shading": { "fill": "F0F0F0", "type": "clear" }, "verticalAlign": "center" }, "imageOverrides": { "transformation": { "width": 400, "height": 300 } } }' ``` ### 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 | ## Convert a font `POST /v2/convert/fonts/convert` Converts a font into a form that can be embedded into a DOCX file: `TTF` / `OTF` uploads are returned unchanged, and `WOFF2` uploads are converted to `TTF`. This is the endpoint the editor extension's [`embedFonts`](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/fonts.md#automatic-embedding) option calls behind the scenes; you can also call it directly. Available from Convert Service **v2.25.0**. > The endpoint is stateless: nothing is stored. Each request is converted and the temporary files > are cleaned up immediately. ### Required headers ```bash Authorization: Bearer ``` ### Body `multipart/form-data`: | Field | Type | Description | Required | | ------------ | -------- | ----------------------------------------------------- | -------- | | `file` | `File` | The font binary (`TTF`, `OTF`, or `WOFF2`). Max 25MB. | Yes | | `fontFamily` | `String` | Font family name, used for logging only. | No | ### Example (cURL) ```bash curl --output MyFont.ttf -X POST "https://api.tiptap.dev/v2/convert/fonts/convert" \ -H "Authorization: Bearer " \ -F "file=@MyFont.woff2" \ -F "fontFamily=My Font" ``` ### Response On success the API returns the embeddable font as a binary download: - **Status**: `200 OK` - **Content-Type**: `font/ttf` ### Error responses | Status | Code | Description | | ------ | ------------------------- | ------------------------------------------------------ | | 400 | None | Request validation error (e.g. no `file` field) | | 413 | `FONT_FILE_TOO_LARGE` | The uploaded font exceeds the 25MB limit | | 422 | `UNSUPPORTED_FONT_FORMAT` | The upload is not a recognized TTF, OTF, or WOFF2 font | | 422 | `FONT_CONVERSION_FAILED` | The WOFF2 → TTF conversion produced no output | | 500 | `FONT_CONVERSION_FAILED` | Unexpected error during conversion |