--- title: "Export EPUB via REST API" description: "Learn how to export Tiptap JSON documents to EPUB format using the Tiptap Conversion REST API v2." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/conversion/export/epub/rest-api" --- # Export EPUB via REST API Learn how to export Tiptap JSON documents to EPUB format using the Tiptap Conversion REST API v2. - **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 EPUB export API converts Tiptap JSON documents into EPUB files. > **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 EPUB `POST /v2/convert/export/epub` The `/v2/convert/export/epub` endpoint converts Tiptap JSON documents into EPUB format. Send a `POST` request with your document as a JSON body to receive a downloadable EPUB file. ### Example (cURL) ```bash curl --output document.epub -X POST "https://api.tiptap.dev/v2/convert/export/epub" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}" }' ``` > **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 JSON document as a string | `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 forwarded to the DOCX step | `undefined` | | `paragraphOverrides` | `Object` | Paragraph-level rendering overrides forwarded to the DOCX step | `undefined` | | `textRunOverrides` | `Object` | Text run rendering overrides forwarded to the DOCX step | `undefined` | | `tableCellOverrides` | `Object` | Table cell rendering overrides forwarded to the DOCX step | `undefined` | | `imageOverrides` | `Object` | Image rendering overrides forwarded to the DOCX step | `undefined` | | `headerFooterOverrides` | `Object` | Per-field overrides scoped to header/footer content (same five keys as the element overrides). See [Element Overrides](#element-overrides). | `undefined` | | `placeholders` | `Object \| false` | Rename map (`{ page?, total? }`) for page-number tokens in headers/footers, matching `Pages.configure({ placeholders })`. Works in every slot shape: plain text, stringified Tiptap JSON, or a Tiptap JSON object. Pass `false` to disable substitution. See [Custom token names](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/rest-api.md#custom-token-names-placeholders). | `undefined` | | `customNodeDsl` | `Object` | [Custom-node DSL](https://tiptap-docs.lin52025i.qzz.io/conversion/export/docx/custom-nodes-dsl.md) rules for rendering custom Tiptap nodes into the exported file. | `undefined` | #### Page Size Configuration The `pageSize` object allows you to customize the dimensions of your exported EPUB 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"` | #### Page Margins Configuration The `pageMargins` object allows you to customize the margins of your exported EPUB 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"` | #### Headers Configuration The `headers` object allows you to customize the headers of your exported EPUB 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 `evenAndOddHeaders` 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`. #### Footers Configuration The `footers` object allows you to customize the footers of your exported EPUB 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 `evenAndOddFooters` 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`. ### Element Overrides EPUB generation goes through the DOCX pipeline, so the same five element overrides accepted by `/export/docx` also apply here when sending Tiptap JSON. They have **no effect** when uploading a pre-built DOCX via `docxFile`. #### Example cURL combining multiple element overrides ```bash curl --output document.epub -X POST "https://api.tiptap.dev/v2/convert/export/epub" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"EPUB with element-level overrides\"}]}]}", "paragraphOverrides": { "spacing": { "before": 200, "after": 200 } }, "textRunOverrides": { "font": "Arial", "size": 24 } }' ``` ### Example with custom page layout ```bash curl --output document.epub -X POST "https://api.tiptap.dev/v2/convert/export/epub" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}", "pageSize": { "width": "210mm", "height": "297mm" }, "pageMargins": { "top": "20mm", "bottom": "20mm", "left": "15mm", "right": "15mm" } }' ``` ### Response On success the API returns the EPUB file as a binary download: - **Status**: `200 OK` - **Content-Type**: `application/epub+zip` - **Content-Disposition**: `attachment; filename=export-{timestamp}.epub` ### 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_EPUB_FILE` | Failed to export intermediate format | | 422 | `FAILED_TO_CONVERT_DOCX_TO_EPUB` | Failed to convert to EPUB |