PDF Generation API Parameters

Our API offers parameters for customizing PDF generation from HTML, URLs, and dynamic templates. This section details each parameter, with examples, to help you tailor the output to your needs.

Endpoint-specific parameters

This page lists common parameters shared across all endpoints. For endpoint-specific parameters (isEncoded, webhook, additionalWebhookHeaders, retryDelays), see the endpoint references:

/v1/direct – immediate PDF response.
/v1/sync – URL-based access.
/v1/async – background processing with webhook.

Source Parameters

Content Source

You must provide exactly one of the following content sources: html, url, or templateId (with templateData). These parameters are mutually exclusive – use only one per API request.

html

Type: string

Required: No

Details: Accepts Base64-encoded HTML content, allowing you to provide the HTML directly for generating a PDF.

Usage:

{
  "html": "PGh0bWw+Cjxib2R5Pgo8cD5UZXN0IHBhcmFncmFwaDwvcD4KPC9ib2R5Pgo8L2h0bWw+Cg=="
}

This example generates a PDF containing the text: “Test paragraph”.

Related reading: Optimizing HTML for Professional PDF Output.

url

Type: string

Required: No

Details: Accepts any valid HTTPS URL up to 2048 characters. Specifies the webpage to be converted to a PDF. PDFBolt rejects non‑HTTPS URLs and test domains (e.g., .test).

Usage:

{
  "url": "https://example.com"
}

templateId

Type: string

Required: No

Details: Specifies the unique identifier (UUID) of a published template to use for PDF generation. When using this parameter, templateData must also be provided to populate the template variables. Templates allow you to separate design from data, making document generation more efficient and maintainable.

Usage:

{
  "templateId": "c2b5f574-19bc-4e34-9049-566176e6dc48",
  "templateData": {
    "customer_name": "John Doe",
    "invoice_number": "INV-001"
  }
}

Template Management

Templates must be created and published through the Templates Dashboard before they can be used via API.
Learn more about template creation and management.
Need a template fast? Generate one with AI from a simple description or reference files.

templateData

Type: object

Required: No (mandatory only if templateId is provided)

Details: Contains the JSON data that replaces placeholder variables in your template to generate the final PDF. Property names in this object must match the variable names used in your template's Handlebars syntax. For example, if your template contains {{customer_name}}, your templateData should include a customer_name property with the actual value.

Usage:

{
  "templateId": "c2b5f574-19bc-4e34-9049-566176e6dc48",
  "templateData": {
    "invoice_number": "INV-001",
    "customer_name": "John Doe",
    "items": [
      {
        "name": "Premium Service",
        "price": "199.99"
      }
    ],
    "total": "199.99",
    "is_paid": true
  }
}

Data Privacy

Template data is used only to generate the requested PDF. In request logs, the html and templateData fields are always redacted after processing is complete.

Your data remains private and secure. See our Privacy Policy and DPA for data protection details.

Page Parameters

emulateMediaType

Type: string

Required: No

Default Value: print

Details: Determines which CSS media type PDFBolt uses when rendering the page for PDF generation.

Allowed Values:

Value	Description
`screen`	Uses CSS screen styles, similar to how the page appears in a browser.
`print`	Uses CSS print styles, intended for printed output.

Usage:

{
  "url": "https://example.com",
  "emulateMediaType": "screen"
}

javaScriptEnabled

Type: boolean

Required: No

Default Value: true

Details: Determines whether JavaScript execution is enabled while rendering the source content for PDF generation.

Value	Description
`true`	Enables JavaScript execution so dynamic content can render.
`false`	Disables JavaScript execution. This may improve performance, but dynamic or interactive content may not render correctly.

Usage:

{
  "url": "https://example.com",
  "javaScriptEnabled": true
}

httpCredentials

Type: object

Required: No

Details: Provides a username and password for source URLs that require HTTP Basic Authentication.

Property Name	Type	Description
`username`	`string`	Username for HTTP Basic Authentication. `required`
`password`	`string`	Password for HTTP Basic Authentication. `required`

Usage:

{
  "url": "https://example.com",
  "httpCredentials": {
    "username": "john",
    "password": "pa55w0rd"
  }
}

viewportSize

Type: object

Required: No

Details: Defines the viewport dimensions for the page, specifying the width and height in pixels. Both width and height must be included in the viewportSize object and must be integers between 1 and 10000.

Property Name	Type	Description
`width`	`integer`	Width of the viewport in pixels. `required`
`height`	`integer`	Height of the viewport in pixels. `required`

Usage:

{
  "url": "https://example.com",
  "viewportSize": {
    "width": 1280,
    "height": 800
  }
}

How viewport size works

Viewport size controls how the page is rendered before PDF conversion, similar to resizing a browser window. This only affects pages that use responsive design with CSS media queries like @media (max-width: 768px). Pages without defined responsive CSS will look the same regardless of viewport size.

isMobile

Type: boolean

Required: No

Default Value: false

Details: Enables mobile device emulation, including mobile viewport behavior and touch events.

Value	Description
`true`	Simulates a mobile device by respecting the meta viewport tag and enabling touch events.
`false`	Disables mobile emulation, rendering the page as it would appear on a desktop device.

Usage:

{
  "url": "https://example.com",
  "isMobile": true
}

When to Use isMobile

Most sites only need viewportSize for mobile layout. Use isMobile: true only for sites that detect mobile devices with JavaScript or use touch-specific CSS.

deviceScaleFactor

Type: number

Required: No

Default Value: 1

Details: Sets the pixel density used when rendering the page. Higher values can make text and images appear sharper in the generated PDF. The allowed range is 1 to 4.

Usage:

{
  "url": "https://example.com",
  "deviceScaleFactor": 2
}

Performance impact

Using a higher deviceScaleFactor can increase the file size and slightly prolong the processing time for generating the PDF.

extraHTTPHeaders

Type: object

Required: No

Details: Adds custom HTTP headers to requests made while rendering the source content. By default, PDFBolt sends these headers with every request the page initiates, including images, stylesheets, scripts, and other resources. You can specify up to 10 headers.

Usage:

{
  "url": "https://example.com",
  "extraHTTPHeaders": {
    "X-extra-header": "test1",
    "X-extra-header2": "test2"
  }
}

Header Scope

To limit headers to only the main page request and exclude sub-resources (images, CSS, JS), set applyExtraHTTPHeadersToAllResources to false. See details below.

applyExtraHTTPHeadersToAllResources

Type: boolean

Required: No

Default Value: true

Details: Determines whether custom headers from extraHTTPHeaders are sent with all resource requests or only with the main page request.

Value	Description
`true`	Headers are sent with every request initiated by the page, including sub-resources like images, stylesheets, and scripts.
`false`	Headers are sent only with the main page request.

Usage:

{
  "url": "https://example.com",
  "extraHTTPHeaders": {
    "X-Custom-Key": "abc123xyz789"
  },
  "applyExtraHTTPHeadersToAllResources": false
}

Usage Notes

Use this parameter only with extraHTTPHeaders.
Set to false if your headers are only intended for the main page request. This prevents errors when external resources (e.g., CDNs, S3) reject custom headers, which can block assets from loading and result in a blank page.

cookies

Type: Array<Object>

Required: No

Details: Adds cookies while rendering the source content. Each cookie must include name, value, and either url or both domain and path to define its scope. You can specify up to 10 cookies.

Property Name	Type	Description
`name`	`string`	The name of the cookie. `required`
`value`	`string`	The value of the cookie. `required`
`url`	`string`	Specifies the URL for which the cookie is valid. `required` if `domain` and `path` are not used
`domain`	`string`	Specifies the domain for which the cookie is valid. `required` if `url` is not used
`path`	`string`	The URL path that must exist in the requested URL for the cookie to be sent. `required` with `domain`
`expires`	`integer`	Expiration date of the cookie in UNIX timestamp format. `optional`
`httpOnly`	`boolean`	Indicates if the cookie is HTTP-only. `optional`
`secure`	`boolean`	Indicates if the cookie is secure. `optional`

Usage:

{
  "url": "https://example.com",
  "cookies": [
    {
      "name": "sessionId",
      "value": "abc123",
      "domain": "example.com",
      "path": "/"
    },
    {
      "name": "userPreferences",
      "value": "darkMode=true",
      "url": "https://example.com",
      "expires": 1739641833,
      "httpOnly": true,
      "secure": true
    }
  ]
}

waitUntil

Type: string

Required: No

Default Value: load

Details: Specifies the event that defines when the page is considered fully loaded during PDF generation. Choose the value that best fits your page's content and loading behavior.

Allowed Values:

Value	Description
`domcontentloaded`	Completes when the `DOMContentLoaded` event fires, meaning the HTML document has been fully parsed.
`load`	Waits for the `load` event, which usually fires after resources such as images and scripts have loaded.
`networkidle`	Waits until there are no active network requests for at least 500 ms.
`commit`	Completes as soon as a network response is received, and the document begins loading.

Usage:

{
  "url": "https://example.com",
  "waitUntil": "networkidle"
}

waitForFunction

Type: string

Required: No

Details: Waits for a JavaScript function to return true in the page context before generating the PDF.

Usage:

{
  "url": "https://example.com",
  "waitForFunction": "() => { return document.readyState === 'complete' && document.fonts.status === 'loaded' && Array.from(document.images).every(img => img.complete); }"
}

What this function does

This example function waits until the document is fully loaded, all fonts are loaded, and all images have finished loading. This helps capture the page after dynamic content has loaded.

waitForSelector

Type: object

Required: No

Details: Waits for a CSS selector to reach a specified state before generating the PDF.

Property Name	Type	Description
`selector`	`string`	CSS selector to target an element. `required`
`state`	`string`	State to wait for. Must be one of the allowed values. `required`

Allowed Values for state:

Value	Description
`attached`	Waits for the element to be present in the DOM.
`detached`	Waits until the element is no longer present in the DOM.
`visible`	Waits for the element to have a non-empty bounding box and not have `visibility: hidden`. Elements with `display: none` are excluded.
`hidden`	Waits for the element to be either detached from the DOM, have an empty bounding box or `visibility: hidden`. Opposite of `visible`.

Usage:

{
  "url": "https://example.com",
  "waitForSelector": {
    "selector": "#removable-element",
    "state": "hidden"
  }
}

Invalid selector

Ensure the CSS selector exists on the target page. A non-existent selector will cause a timeout error.

timeout

Type: integer

Required: No

Default Value: 30000

Details: Defines the maximum time in milliseconds to wait for the page to load or for specific conditions to be met. The acceptable range is 1 ms up to your plan maximum:

Free plan: up to 30000 ms (30 seconds).
Paid plans: up to 60000 ms (1 minute).

If the timeout is exceeded, the request will fail with a timeout error.

Usage:

{
  "url": "https://example.com",
  "timeout": 30000
}

Common Timeout Mistake

Note that the timeout value must be provided in milliseconds, not seconds. A common mistake is entering 30 instead of 30000 for a 30-second timeout.

PDF Layout

format

Type: string

Required: No

Default Value: Letter

Details: Specifies the paper format for the generated PDF. If both format and custom page dimensions (width or height) are provided, format takes priority.

Allowed Values:

Value	Size in Inches	Size in cm
`Letter`	8.5in x 11in	21.6cm x 27.9cm
`Legal`	8.5in x 14in	21.6cm x 35.6cm
`Tabloid`	11in x 17in	27.9cm x 43.2cm
`Ledger`	17in x 11in	43.2cm x 27.9cm
`A0`	33.1in x 46.8in	84cm x 118.9cm
`A1`	23.4in x 33.1in	59.4cm x 84cm
`A2`	16.54in x 23.4in	42cm x 59.4cm
`A3`	11.7in x 16.54in	29.7cm x 42cm
`A4`	8.27in x 11.7in	21cm x 29.7cm
`A5`	5.83in x 8.27in	14.8cm x 21cm
`A6`	4.13in x 5.83in	10.5cm x 14.8cm

Usage:

{
  "url": "https://example.com",
  "format": "A4"
}

landscape

Type: boolean

Required: No

Default Value: false

Details: Defines the orientation of the generated PDF.

Value	Description
`true`	Generates the PDF in landscape mode.
`false`	Generates the PDF in portrait mode (default).

Usage:

{
  "url": "https://example.com",
  "landscape": true
}

width

Type: string | number

Required: No

Details: Defines the custom page width for the generated PDF. Use this instead of format when you need a custom page size. You can provide a number of pixels or a string with px, in, cm, or mm units.

Supported Units:

px – pixel
in – inch
cm – centimeter
mm – millimeter

Default Unit

If no unit is specified, the value is interpreted as pixels.

Examples:

"width": 100 – sets the page width to 100 pixels.
"width": "100px" – sets the page width to 100 pixels.
"width": "10cm" – sets the page width to 10 centimeters.

Usage:

{
  "url": "https://example.com",
  "width": "15cm"
}

height

Type: string | number

Required: No

Details: Defines the custom page height for the generated PDF. Use this instead of format when you need a custom page size. You can provide a number of pixels or a string with px, in, cm, or mm units. If no unit is specified, the value is interpreted as pixels.

Usage:

{
  "url": "https://example.com",
  "height": "800px"
}

margin

Type: object

Required: No

Details: Specifies the page margins for the generated PDF. By default, no margins are applied. Provide at least one margin property (top, right, left, bottom) – an empty margin object is treated as if margin was omitted. Each margin accepts a number of pixels or a string with px, in, cm, or mm units.

Property Name	Type	Description
`top`	`string` \| `number`	Specifies the top margin.
`right`	`string` \| `number`	Specifies the right margin.
`left`	`string` \| `number`	Specifies the left margin.
`bottom`	`string` \| `number`	Specifies the bottom margin.

Usage:

{
  "url": "https://example.com",
  "margin": {
    "top": "30px",
    "right": "20px",
    "left": "20px",
    "bottom": "30px"
  }
}

pageRanges

Type: string

Required: No

Details: Specifies the page ranges to include in the PDF. Accepts a comma-separated list of page ranges or individual pages, such as 1-3, 5, 8-11. If omitted, the PDF includes all pages.

Usage:

{
  "url": "https://example.com",
  "pageRanges": "1-7"
}

preferCssPageSize

Type: boolean

Required: No

Default Value: false

Details: Specifies whether the PDF generation should prioritize the CSS @page size defined in the content.

Value	Description
`true`	The PDF will use the dimensions specified in the `@page` CSS rule.
`false`	The content will scale automatically to fit the page size set by `width`, `height`, or `format`.

Usage:

{
  "url": "https://example.com",
  "preferCssPageSize": true
}

printBackground

Type: boolean

Required: No

Default Value: false

Details: Specifies whether the PDF should include background graphics like colors and images.

Value	Description
`true`	Background graphics (e.g., colors, images) will be included in the PDF.
`false`	Background graphics will be excluded, producing a simpler, more minimalistic PDF.

Usage:

{
  "url": "https://example.com",
  "printBackground": true
}

For Styled PDFs

Set printBackground: true to include CSS background colors, gradients, and background images in your PDF. Essential for invoices, certificates, dashboards, and marketing materials.

scale

Type: number

Required: No

Default Value: 1

Details: Specifies the scaling factor for rendering the content in the generated PDF. The acceptable range for this parameter is between 0.1 and 2.

Usage:

{
  "url": "https://example.com",
  "scale": 1.5
}

displayHeaderFooter

Type: boolean

Required: No

Default Value: false

Details: Specifies whether to include a header and footer in the generated PDF. This parameter only takes effect when used with the headerTemplate and/or footerTemplate parameters to define their content.

Value	Description
`true`	Header and footer will be displayed on each page of the PDF.
`false`	No header or footer will be included in the PDF.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "footerTemplate": "PGRpdiBzdHlsZT0id2lkdGg6IDEwMCU7IHRleHQtYWxpZ246IGNlbnRlcjsgZm9udC1zaXplOiAxMnB4OyI+PHNwYW4gY2xhc3M9InBhZ2VOdW1iZXIiPjwvc3Bhbj4gb2YgPHNwYW4gY2xhc3M9InRvdGFsUGFnZXMiPjwvc3Bhbj48L2Rpdj4=",
  "margin": {
    "bottom": "40px"
  }
}

This produces a page-number footer (e.g., "1 of 5"). See footerTemplate for details.

headerTemplate

Type: string

Required: No

Details: Specifies the HTML template for the page header. The template must be a valid Base64-encoded HTML string with specific classes used to dynamically inject values during PDF generation.

The following classes are used to inject dynamic values:

Class	Description
`date`	Current date and time (e.g., "12/31/25, 5:30 PM").
`title`	Document title from the `<title>` tag.
`url`	Full URL of the source page being converted to PDF.
`pageNumber`	Current page number in the generated PDF.
`totalPages`	Total number of pages in the generated PDF document.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "headerTemplate": "PGRpdiBzdHlsZT0id2lkdGg6IDEwMCU7IHRleHQtYWxpZ246IGNlbnRlcjsgZm9udC1zaXplOiAxMHB4OyBjb2xvcjogZ3JheTsiPg0KICAgIDxzcGFuIGNsYXNzPSJ0aXRsZSI+PC9zcGFuPiB8IDxzcGFuIGNsYXNzPSJ1cmwiPjwvc3Bhbj4gfCA8c3BhbiBjbGFzcz0iZGF0ZSI+PC9zcGFuPg0KPC9kaXY+DQo=",
  "margin": {
    "top": "30px"
  }
}

This example generates a PDF with the following header:

<div style="width: 100%; text-align: center; font-size: 10px; color: gray;">
    <span class="title"></span> | <span class="url"></span> | <span class="date"></span>
</div>

footerTemplate

Type: string

Required: No

Details: Specifies the Base64-encoded HTML template for the page footer. Use the same conventions as the headerTemplate.

Usage:

{
  "url": "https://example.com",
  "displayHeaderFooter": true,
  "footerTemplate": "PGRpdiBzdHlsZT0id2lkdGg6IDEwMCU7IHRleHQtYWxpZ246IGNlbnRlcjsgZm9udC1zaXplOiAxMnB4OyI+DQogICAgPHNwYW4gY2xhc3M9InBhZ2VOdW1iZXIiPjwvc3Bhbj4gb2YgPHNwYW4gY2xhc3M9InRvdGFsUGFnZXMiPjwvc3Bhbj4NCjwvZGl2Pg==",
  "margin": {
    "bottom": "40px"
  }
}

This example generates a PDF with the footer:

<div style="width: 100%; text-align: center; font-size: 12px;">
    <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>

Header & Footer Limitations

Headers and footers are rendered in an isolated context with no network access and no connection to the main page. Chromium treats them as simple HTML templates with limited capabilities.

What does NOT work:

External images – <img src="https://..."> will not load.
External fonts – Google Fonts, custom fonts via @import or <link> are not supported.
Scripts – <script> tags are ignored, JavaScript is not executed.
External CSS – <link rel="stylesheet"> will not work.
Template variables – Handlebars syntax like {{variableName}} is not supported in header/footer templates.

What WORKS in Header & Footer

Inline CSS – styles directly in style="" attribute or within <style> tag.
Inline SVG – <svg>...</svg> embedded directly in the template.
Base64 images – <img src="data:image/png;base64,...">.
Built-in classes – date, title, url, pageNumber, totalPages (use as <span class="pageNumber"></span>).

Styling tips:

Ensure that your HTML templates are valid Base64-encoded strings.
Adjust margins – set the top margin for headers and the bottom margin for footers to ensure visibility and avoid clipping.
Check visibility – verify font size and color. CSS rules defined in the body do not affect headers or footers.

Accessibility

tagged

Type: boolean

Required: No

Default Value: false

Details: Determines whether to generate tagged PDFs that include structural information for screen readers and assistive technologies. Tagged PDFs improve accessibility but compliance with formal standards (such as PDF/UA) depends on your HTML semantics, alt text, heading order, language metadata, and reading order – tagged: true alone does not guarantee full conformance.

Value	Description
`true`	Generates a tagged PDF with structural markup that improves accessibility for assistive technologies.
`false`	Generates a standard PDF without accessibility tags.

Usage:

{
  "url": "https://example.com",
  "format": "A4",
  "tagged": true
}

Size Considerations

File sizes are typically 5-15% larger due to embedded structural information.

Print Production

printProduction

Type: object

Required: No

Details: Configures professional printing options including PDF/X standards compliance. Use this parameter when generating PDFs intended for commercial printing. Requires the Growth plan or higher.

If you already have a PDF file and need a one-off conversion, use the free PDF/X converter. The printProduction API parameter below is for PDFs generated from HTML, URLs, or templates.

Property Name	Type	Description
`pdfStandard`	`string`	PDF/X standard for print compliance. `optional`
`colorSpace`	`string`	Target color space for PDF output. `optional`
`iccProfile`	`string`	ICC color profile for RGB-to-CMYK conversion. `optional`
`preserveBlack`	`boolean`	Preserve pure black during CMYK conversion. `optional`

Usage:

{
  "url": "https://example.com",
  "printProduction": {
    "pdfStandard": "pdf-x-4",
    "colorSpace": "cmyk",
    "iccProfile": "fogra39",
    "preserveBlack": true
  }
}

pdfStandard

Type: string

Required: No

Details: Generates a PDF compliant with industry-standard PDF/X specifications. PDF/X standards ensure reliable printing by embedding all necessary information and restricting features that could cause printing issues. Generated PDFs pass Adobe Preflight validation for the selected standard.

Allowed Values:

Value	PDF Version	Description
`pdf‑x‑4`	PDF 1.6	Modern standard supporting transparency, layers, and OpenType fonts. Recommended for most professional printing.
`pdf‑x‑1a`	PDF 1.3	Strictest compliance. NO transparency, NO RGB colors, NO layers. Maximum compatibility with legacy printing equipment.

Usage:

{
  "url": "https://example.com",
  "format": "A4",
  "printBackground": true,
  "printProduction": {
    "pdfStandard": "pdf-x-4"
  }
}

Automatic CMYK Conversion

Using pdfStandard automatically converts all RGB colors to CMYK using the specified ICC profile, ensuring optimal results on commercial printing presses.

Choosing Between PDF/X-4 and PDF/X-1a

PDF/X-4 (recommended):

Preserves transparency (drop shadows, gradients, opacity).
Supports OpenType fonts.
Modern printing workflows and equipment.
Ideal for designs with CSS shadows, gradients, or transparency effects.
Learn more about PDF/X-4 →

PDF/X-1a (maximum compatibility):

Flattens all transparency.
Converts to older PDF format.
Compatible with legacy printing systems.
Use when your print shop specifically requires it.
Learn more about PDF/X-1a →

For a general overview of PDF/X standards, see PDF/X on Wikipedia.

Transparency in PDF/X-1a

When using pdf-x-1a with designs containing transparency (CSS shadows, gradients, opacity), elements will be flattened. This may cause visible artifacts or "stitching" lines at edges. Additionally, text involved in transparency effects may be outlined (converted to vector paths) or rasterized (converted to pixels), making it non-selectable and non-searchable in the resulting PDF. For designs with transparency effects, pdf-x-4 is recommended.

colorSpace

Type: string

Required: No

Default Value: rgb

Details: Sets the target color space for the generated PDF. Use cmyk when producing files for professional printing, or keep the default rgb for digital viewing (screens, emails, web).

Allowed Values:

Value	Description
`rgb`	RGB color space (default). Best for digital viewing – screens, emails, and web distribution.
`cmyk`	CMYK color space. Required for professional and commercial printing. Converts all colors from RGB to CMYK.

Usage:

{
  "url": "https://example.com",
  "format": "A4",
  "printBackground": true,
  "printProduction": {
    "colorSpace": "cmyk"
  }
}

When to Use CMYK

Choose cmyk when your PDF will be sent to a commercial printer. CMYK (Cyan, Magenta, Yellow, Key/Black) matches the four-ink process used by printing presses, ensuring colors reproduce accurately on paper. For PDFs viewed only on screens, rgb provides a wider color gamut and smaller file size. Learn more about the CMYK color model.

iccProfile

Type: string

Required: No

Default Value: fogra39

Details: Specifies the ICC color profile used for RGB-to-CMYK conversion. Each profile is calibrated for specific printing conditions (paper type, ink coverage, regional standards). The profile defines how RGB colors are mapped to CMYK values. If you provide iccProfile, you must also set colorSpace to cmyk.

Allowed Values:

Value	Profile Name	Description
`fogra39`	Coated FOGRA39 (ISO 12647-2:2004)	European standard for coated paper. The most widely used profile in Europe. ICC Registry
`fogra51`	PSO Coated v3 (FOGRA51)	Modern European standard. Updated replacement for FOGRA39 with improved color accuracy. ICC Registry
`swop`	SWOP 2006 Coated 5	North American standard for web offset printing on coated paper. Idealliance SWOP
`gracol`	GRACoL 2006 Coated 1	North American standard for commercial printing on coated paper. Idealliance GRACoL

Usage:

{
  "url": "https://example.com",
  "format": "A4",
  "printBackground": true,
  "printProduction": {
    "colorSpace": "cmyk",
    "iccProfile": "fogra51"
  }
}

Choosing an ICC Profile

Printing in Europe?

Use fogra51 for modern workflows, or fogra39 for maximum compatibility with existing European print infrastructure.

Printing in North America?

Use gracol for commercial sheet-fed printing, or swop for web offset printing (magazines, catalogs).

preserveBlack

Type: boolean

Required: No

Default Value: true

Details: Controls how pure black (#000000 / rgb(0,0,0)) is handled during CMYK conversion. When enabled, pure black is mapped directly to 100% K (Key) ink only (C:0 M:0 Y:0 K:100), producing crisp text and sharp lines. When disabled, black is converted through the ICC profile into a "rich black" mix of all four inks (e.g., C:75 M:68 Y:67 K:90). Requires colorSpace set to cmyk (or pdfStandard provided).

Allowed Values:

Value	Description
`true`	(default) Pure black → 100% K only. Sharp, crisp black for text and fine lines.
`false`	Pure black → Rich black through ICC profile. Deeper black for large solid areas.

Usage:

{
  "url": "https://example.com",
  "format": "A3",
  "printBackground": true,
  "printProduction": {
    "colorSpace": "cmyk",
    "preserveBlack": false
  }
}

K-only Black vs Rich Black

For documents that are primarily text or contain fine black lines, keep the default true – pure K-only black avoids registration issues and keeps text razor-sharp. This is the right choice for most documents.
Set preserveBlack: false when your design has large solid black areas (backgrounds, banners, full-bleed panels) where you want a deeper, richer black appearance. Rich black uses all four CMYK inks to produce a denser black than K-ink alone.

Output Parameters

contentDisposition

Type: string

Required: No

Default Value: inline

Details: Controls the Content-Disposition header behavior for the generated PDF, determining how browsers handle the file.

Allowed Values:

Value	Description
`inline`	The PDF is displayed directly in the browser (default behavior).
`attachment`	The PDF is downloaded as a file, prompting the user with a Save As dialog.

Usage:

{
  "url": "https://example.com",
  "contentDisposition": "attachment"
}

This will generate a PDF with the following header:

Content-Disposition: attachment

Combining with filename

You can use contentDisposition together with the filename parameter to control both the download behavior and the filename:

{
  "url": "https://example.com",
  "contentDisposition": "attachment",
  "filename": "custom_file_name"
}

Result:

Content-Disposition: attachment; filename="custom_file_name.pdf"

filename

Type: string

Required: No

Details: Specifies the filename for the generated PDF. This name will be embedded in the Content-Disposition header so browsers and automation tools (such as n8n, Zapier, and Make) can correctly recognize and use the specified filename when downloading or processing the PDF.

Constraints:

Maximum length: 255 characters.
Allowed characters: alphanumeric (a–z, A–Z, 0–9), dots (.), underscores (_), hyphens (-).
If the .pdf extension is omitted, it will be added automatically.

Usage:

{
  "url": "https://example.com",
  "filename": "custom_file_name"
}

This will generate a PDF with the following header:

Content-Disposition: inline; filename="custom_file_name.pdf"

Integration with Automation Tools

When using PDFBolt with automation platforms like n8n, Zapier, or Make, the filename parameter ensures that downloaded PDFs use your specified name instead of a generic or UUID-based filename.

compression

Type: string

Required: No

Details: Applies compression to reduce the final PDF file size. This is most useful for image-heavy PDFs. The compression level controls the tradeoff between file size and image quality.

If you already have a PDF file and want to reduce its size without writing code, use the free PDF compressor. The compression API parameter below applies during HTML, URL, or template PDF generation.

Allowed Values:

Value	Description
`lossless`	Downscales images only – no quality loss.
`low`	Highest quality – largest file size.
`medium`	Balanced quality – moderate file size.
`high`	Lowest quality – smallest file size.

Usage:

{
  "url": "https://example.com",
  "compression": "low"
}

When to Use Compression

Compression is most effective on image-heavy PDFs. Text-only PDFs will see minimal size reduction.

What does "lossless" do?

The lossless compression level reduces file size by downscaling images to their rendered display size (×2 for print quality) without applying any JPEG quality reduction. This is useful for users who need smaller files but want to preserve original image quality. Duplicate images are also de-duplicated automatically.

Source Parameters​

html​

url​

templateId​

templateData​

Page Parameters​

emulateMediaType​

javaScriptEnabled​

httpCredentials​

viewportSize​

isMobile​

deviceScaleFactor​

extraHTTPHeaders​

applyExtraHTTPHeadersToAllResources​

cookies​

waitUntil​

waitForFunction​

waitForSelector​

timeout​

PDF Layout​

format​

landscape​

width​

height​

margin​

pageRanges​

preferCssPageSize​

printBackground​

scale​

displayHeaderFooter​

headerTemplate​

footerTemplate​

Accessibility​

tagged​

Print Production​

printProduction

pdfStandard​

colorSpace​

iccProfile​

preserveBlack​

Output Parameters​

contentDisposition​

filename​

compression​

Source Parameters

html

url

templateId

templateData

Page Parameters

emulateMediaType

javaScriptEnabled

httpCredentials

viewportSize

isMobile

deviceScaleFactor

extraHTTPHeaders

applyExtraHTTPHeadersToAllResources

cookies

waitUntil

waitForFunction

waitForSelector

timeout

PDF Layout

format

landscape

width

height

margin

pageRanges

preferCssPageSize

printBackground

scale

displayHeaderFooter

headerTemplate

footerTemplate

Accessibility

tagged

Print Production

pdfStandard

colorSpace

iccProfile

preserveBlack

Output Parameters

contentDisposition

filename

compression