Print options

Every capability of the engine, in one options object — on every print, template print, image and layout request, and job.

curl https://api.reflowpdf.com/v1/pdf \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Q3 report</h1>…",
    "options": {
      "paper": { "size": "A4", "margin": "20mm" },
      "metadata": { "author": "Finance", "keywords": "q3, revenue" },
      "header_footer": { "footer": "Page {pageNum} of {totalPages}", "footer_align": "right" },
      "watermark": { "text": "DRAFT", "opacity": 0.08 },
      "encryption": { "owner_password": "…", "permissions": ["print-high", "copy"] },
      "compression": "smallest"
    }
  }' -o report.pdf

const pdf = await reflow.pdf.create({
  html,
  options: {
    paper: { size: 'A4', margin: '20mm' },
    metadata: { author: 'Finance', keywords: 'q3, revenue' },
    header_footer: { footer: 'Page {pageNum} of {totalPages}', footer_align: 'right' },
    watermark: { text: 'DRAFT', opacity: 0.08 },
    encryption: { owner_password: process.env.PDF_OWNER_PASSWORD, permissions: ['print-high', 'copy'] },
    compression: 'smallest',
  },
})

pdf = client.pdf.create(
    html=html,
    options={
        "paper": {"size": "A4", "margin": "20mm"},
        "metadata": {"author": "Finance", "keywords": "q3, revenue"},
        "header_footer": {"footer": "Page {pageNum} of {totalPages}", "footer_align": "right"},
        "watermark": {"text": "DRAFT", "opacity": 0.08},
        "encryption": {"owner_password": os.environ["PDF_OWNER_PASSWORD"], "permissions": ["print-high", "copy"]},
        "compression": "smallest",
    },
)

Every option is optional and checked before anything prints: an unknown one, a wrong value, or two that a standard forbids together is 400 invalid_request with detail naming it; nothing is printed or counted.

Declarations#

Option	Value	What it does
`pdf_ua`	`1` or `2`	Claim PDF/UA-1 or PDF/UA-2 (Pro, Max).
`pdf_a`	`"3a"` or `"1b"`	Claim PDF/A-3a or PDF/A-1b (Pro, Max).
`pdf_x`	`{ standard, output_intent, profile }`	Claim PDF/X-4 or PDF/X-1a for a print condition (Pro, Max).
`tagged`	`true` (default) or `false`	The structure for screen readers and reflow. `false`: a smaller untagged file; not with `pdf_ua` or `pdf_a: "3a"`.

What each claims, which go together, print conditions and your own ICC profile: PDF/UA, PDF/A, PDF/X.

The document's words#

Option	Value	What it does
`title`	text	The PDF's title; else the document's `<title>`, else its first `<h1>`.
`lang`	BCP 47, `"en"`, `"de-CH"`	The language when `<html lang>` names none: screen readers and hyphenation use it.
`metadata`	`{ author, subject, keywords }`	Over the document's `<meta name="author\|description\|keywords">`; written to the document information and the XMP.

What every page carries#

Option	Value	What it does
`header_footer`	`{ header, footer, header_align, footer_align, font_size, color }`	A line of text in the top and bottom margins; `{pageNum}` and `{totalPages}` are replaced on each page. Aligned `left`, `center` (default) or `right`; `font_size` a CSS length (default `7.5pt`).
`watermark`	`{ text }` or `{ image }`, and `font_size`, `color`, `opacity`, `angle`, `above`, `tile`, `tile_spacing`, `position`, `image_width`, `image_height`	A stamp on every page, behind the content (over it with `above: true`), marked as an artifact so screen readers skip it. `image`: an https or `data:` URL. `tile: true` repeats it `tile_spacing` `[x, y]` points apart; `position: { x, y }` places one stamp (points from the top-left) instead of the centre.

Headers and footers styled with the document (fonts, rules, running titles, counters) are CSS: @page { @top-right { content: string(chapter) } @bottom-center { content: counter(page) " / " counter(pages) } }. header_footer is for adding a line to a document you do not edit.

What the file is#

Option	Value	What it does
`encryption`	`{ owner_password, user_password, permissions, algorithm }`	AES-256 (ISO 32000-2) by default; `algorithm: "rc4-128"` only for readers older than Acrobat 9. `owner_password` is required (it lifts the permissions); `user_password` is asked to open the file; empty, it opens without one. Not with `pdf_a` or `pdf_x`.
`attachments`	`[{ filename, content, mime_type, description, relationship, element }]`	Up to 20 files, 10 MB together, `content` in base64. `relationship` (`data`, `source`, `alternative`, `supplement`, `unspecified`) and `element` (the `id` it belongs to) make them PDF/A-3 associated files with `pdf_a: "3a"`, such as an invoice's data beside it. Not with `pdf_a: "1b"` or `pdf_x`.
`compression`	`"fast"`, `"default"`, `"smallest"`	How hard streams are compressed, losslessly: images are never resampled, text stays text.
`object_streams`	`true` (default) or `false`	Objects packed into object streams: smaller files. `false`: a classic cross-reference table, for readers older than PDF 1.5.

The permissions an encryption grants: print (low resolution), print-high, modify, copy, annotate, fill-forms, assemble. What is not listed is not allowed, except extraction for accessibility: screen readers may always read the file (ISO 32000-2 requires it, and PDF/UA too).

How the document lays out#

Option	Value	What it does
`paper`	`{ size, orientation, margin }`	The paper where the document's CSS names none (default A4, 20 mm); the document's own `@page` wins, property by property. See HTML to PDF.
`color_scheme`	`"light"` (default) or `"dark"`	The answer to `@media (prefers-color-scheme)`.
`default_font_size`	a CSS length, `"12pt"`	CSS `medium`: the size `rem` and unstyled text start from.
`print_scale`	0.06–0.99	Print the document shrunk by this factor, as a browser's print scale.
`shrink_to_fit`	`false` (default)	Shrink a document wider than its paper to fit, as browsers do. Off, lengths stay physical: 20 mm is 20 mm.
`base_css`	CSS, up to 1 MB	Your stylesheet below the document's own (the user-agent origin): defaults it may override, such as a house font or table borders.
`input_format`	`"html"` (default) or `"xhtml"`	Parse the document as XML (namespaces, self-closing elements).
`base_url`	an http(s) URL	Where the document's relative addresses (`logo.png`, `../styles.css`) point: its `<base href>`, unless it names its own.
`javascript`	true / false	Run the document's scripts before it prints: JavaScript.
`allow_remote`	`true` (default) or `false`	Fetch the document's https and http images, stylesheets and fonts (public addresses only). `false`: print with what it carries in `data:` URLs; the rest is named in `skipped_resources`.
`max_pages`	1–5000	Print at most this many pages; the rest is left out and not counted.