--- title: "Export PDF via REST API" description: "Learn how to export Tiptap JSON documents to PDF format using the Tiptap Conversion REST API v2." canonical_url: "https://tiptap.dev/docs/conversion/export/pdf/rest-api" --- # Export PDF via REST API Learn how to export Tiptap JSON documents to PDF 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** To use the Convert REST API retrieve your App ID and Convert secret from [your dashboard](https://cloud.tiptap.dev/v2/cloud/convert). The PDF export API converts Tiptap JSON documents into PDF 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 PDF `POST /v2/convert/export/pdf` The `/v2/convert/export/pdf` endpoint converts Tiptap JSON documents into PDF format. Send a `POST` request with your document as a JSON body to receive a downloadable PDF file. ### Example (cURL) ```bash curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \ -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\":\"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` | | `X-App-Id` | The Convert App-ID from the Convert settings page: [https://cloud.tiptap.dev/v2/cloud/convert](https://cloud.tiptap.dev/v2/cloud/convert) | | `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` | | `customFonts` | `Array` | Custom font files to provision (on-premises only) | `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` | #### Page Size Configuration The `pageSize` object allows you to customize the dimensions of your exported PDF 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 PDF 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 PDF document. Each slot (`default`, `first`, `even`) accepts any of: a plain text string, a stringified Tiptap JSONContent, or a Tiptap JSONContent object sent directly in the JSON body. | 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 (bold, italic, links, etc.). Produce it with `JSON.stringify(yourHeaderDoc)`. > - A **Tiptap JSONContent object.** The same rich content, sent as a nested JSON object inside the request body (no stringification needed). > > Objects are validated at the slot level and must include a `type` field. Invalid shapes return `400 Bad Request`. #### Footers Configuration The `footers` object allows you to customize the footers of your exported PDF document. Slots accept the same three shapes as headers. | 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. | ### Example with headers and footers ```bash curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \ -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\":\"Hello World\"}]}]}", "headers": { "default": { "type": "doc", "content": [ { "type": "paragraph", "content": [{ "type": "text", "text": "My Header" }] } ] } }, "footers": { "default": "Company name, 2026" } }' ``` #### Custom Fonts Configuration > **On-premises only:** > > Custom fonts are only available in on-premises deployments. If you're interested in using custom fonts with Tiptap's cloud service, please [contact us about our Enterprise plan](https://tiptap.dev/pricing). The `customFonts` array allows you to provision custom font files for PDF generation. Each entry specifies a font file URL and its family name: | Property | Type | Description | | ------------ | -------- | ------------------------------------------------------------- | | `url` | `string` | HTTPS URL pointing directly to a `.ttf` or `.woff2` font file | | `fontFamily` | `string` | Font family name as used in the document | ### Example with custom fonts (on-premises) ```bash curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \ -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\":\"Hello World\"}]}]}", "customFonts": [ { "url": "https://your-cdn.com/fonts/CustomFont-Regular.ttf", "fontFamily": "Custom Font" } ] }' ``` ### Element Overrides PDF 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.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \ -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\":\"PDF with element-level overrides\"}]}]}", "paragraphOverrides": { "spacing": { "before": 200, "after": 200 } }, "textRunOverrides": { "font": "Arial", "size": 24 } }' ``` ### Example with custom page layout ```bash curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \ -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\":\"Hello World\"}]}]}", "pageSize": { "width": "210mm", "height": "297mm" }, "pageMargins": { "top": "20mm", "bottom": "20mm", "left": "15mm", "right": "15mm" } }' ``` ### Response On success the API returns the PDF file as a binary download: - **Status**: `200 OK` - **Content-Type**: `application/pdf` - **Content-Disposition**: `attachment; filename=export-{timestamp}.pdf` ### Error responses | Status | Code | Description | | ------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `NO_DOCUMENT_PROVIDED` | No document was provided in the body | | 400 | *(validation)* | A `headers` / `footers` slot contains an object without a `type` field, or another schema-level problem. The response body includes a ZodError describing which field failed. | | 422 | `FAILED_TO_PARSE_DOCX_FILE` | Failed to parse JSON inputs | | 422 | `FAILED_TO_EXPORT_PDF_FILE` | Failed to export intermediate format | | 403 | `CUSTOM_FONTS_NOT_AVAILABLE` | Custom fonts are only available in on-premises deployments | | 422 | `FAILED_TO_CONVERT_DOCX_TO_PDF` | Failed to convert to PDF |