Export PDF via REST API
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.
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)
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.
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 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 |
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:
| 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 evenAndOddHeaders 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.
Footers Configuration
The footers object allows you to customize the footers of your exported PDF 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 evenAndOddFooters 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.
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.
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)
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"
}
]
}'Example with custom page layout
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 |
| 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 |