Export PDF via REST API

Available in Start planBetav2.12.0

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`
`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

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.

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"
        }
      ]
    }'

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.

The five element override objects let you tune how individual DOCX elements (tables, paragraphs, text runs, table cells, images) are rendered. Each override is forwarded to the underlying DOCX conversion library as a base default; per-node values from the document still win where they are computed.

No deep merging

Nested objects inside an override (for example borders, margins, transformation) are replaced entirely, not deep-merged. When customizing one side of a border, provide every side you need so undefined values do not slip through.

`tableOverrides`

Defaults applied to every table. Most useful properties:

Property	Type	Description
`borders`	`Object`	Per-side definitions for `top`, `bottom`, `left`, `right`, `insideHorizontal`, `insideVertical`. Each accepts `{ style, size, color }`.
`margins`	`Object`	Default cell margins `{ top, bottom, left, right }` (twentieths of a point).
`width`	`Object`	Table width `{ size, type }` where `type` is `"pct"`, `"dxa"`, or `"auto"`.
`layout`	`string`	`"fixed"` or `"autofit"`.
`alignment`	`string`	`"left" \| "center" \| "right" \| "start" \| "end"`.
`cantSplit`	`boolean`	Prevent the table from splitting across pages.
`visuallyRightToLeft`	`boolean`	Render the table right-to-left.

`paragraphOverrides`

Defaults applied to every paragraph. Most useful properties:

Property	Type	Description
`spacing`	`Object`	`{ before, after, line, lineRule }` in twentieths of a point. `line` is overwritten by computed line height.
`alignment`	`string`	`"left" \| "center" \| "right" \| "justified" \| "start" \| "end"`.
`indent`	`Object`	`{ left, right, firstLine, hanging, start, end }` in twentieths of a point.
`keepNext`	`boolean`	Keep this paragraph with the next one.
`keepLines`	`boolean`	Keep all lines in the paragraph together.
`pageBreakBefore`	`boolean`	Insert a page break before the paragraph.
`bidirectional`	`boolean`	Render paragraph right-to-left.
`style`	`string`	Reference to a paragraph style id defined in `styleOverrides`.

`textRunOverrides`

Defaults applied to every text run. Per-mark formatting (bold, italic, color, …) still overrides these values. Most useful properties:

Property	Type	Description
`font`	`string`	Font family name.
`size`	`number`	Font size in half-points (`24` = 12pt).
`bold`	`boolean`	Render bold by default.
`italics`	`boolean`	Render italic by default.
`underline`	`Object`	`{ type, color }` — e.g. `{ type: "single", color: "auto" }`.
`strike`	`boolean`	Strikethrough.
`color`	`string`	Hex color without the leading `#` (`"FF0000"`).
`highlight`	`string`	Predefined highlight color name (`"yellow"`, `"green"`, …).
`superScript`	`boolean`	Render as superscript.
`subScript`	`boolean`	Render as subscript.

`tableCellOverrides`

Defaults applied to every table cell. Most useful properties:

Property	Type	Description
`shading`	`Object`	`{ fill, type, color }` — e.g. `{ fill: "F0F0F0", type: "clear" }`.
`verticalAlign`	`string`	`"top" \| "center" \| "bottom"`.
`borders`	`Object`	Per-side cell border definitions, same shape as `tableOverrides.borders`.
`margins`	`Object`	Cell padding `{ top, bottom, left, right }` in twentieths of a point.
`width`	`Object`	Cell width `{ size, type }`.

`imageOverrides`

Defaults applied to every image. Image dimensions computed from the document (intrinsic size or user-resized values) still win where present. Most useful properties:

Property	Type	Description
`transformation`	`Object`	`{ width, height, rotation?, flip? }` — pixels at 96 dpi.
`altText`	`Object`	`{ title, description, name }`.
`floating`	`Object`	Floating positioning options (anchor, alignment, offset, wrap).

Example cURL combining multiple element overrides

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

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

PreviouslyPDF

Next upODT