API Reference
Use one shared options object to control PDF behavior
This page is the single shared reference for the render-request options object. Use it for layout, timing, watermark, metadata, and runtime asset settings across rendering routes.
Object contract
Auth context
X-API-Key on rendering routes
The object is consumed on API-key authenticated rendering endpoints.
Object location
request body options field
Include it on POST /v1/pdf and on POST /v1/pdf/batch item payloads asitems[].options.
Field behavior
all fields optional
Send only the fields you need; omitted fields use endpoint defaults.
Layout
Control page geometry and print chrome
Use layout fields for page format, orientation, backgrounds, margins, header and footer templates, scale, and CSS page-size behavior.
options.format
optional enum: Letter | A4 | A5 | A3 | Legal | Tabloid
Sets output paper format.
options.landscape
optional boolean
Switches orientation to landscape when true.
options.printBackground
optional boolean
Includes CSS backgrounds in the PDF output.
options.margin
optional object: top | right | bottom | left (string)
Defines per-side margin strings such as 0.5in or 12mm.
options.displayHeaderFooter
optional boolean
Enables header and footer templates.
options.headerTemplate
optional string, max 5000 chars
Header HTML fragment.
options.footerTemplate
optional string, max 5000 chars
Footer HTML fragment.
options.scale
optional number, 0.1-2
Scales rendered content before PDF capture.
options.preferCSSPageSize
optional boolean
Uses CSS @page size when true.
Timing
Control readiness and timeout budget
Use timing fields when source pages depend on async data, scripts, or delayed hydration.
options.waitUntil
optional enum: load | domcontentloaded | networkidle
Navigation readiness milestone before capture starts.
options.waitForSelector
optional string, max 255 chars
Additional selector that must exist before capture.
options.delayMs
optional integer, 0-60000
Extra post-readiness delay to stabilize late-rendering content.
options.timeoutMs
optional integer, 1000-300000
Total render timeout budget in milliseconds.
Watermark
Apply a document watermark
Use watermark fields for draft, preview, internal, or compliance labeling.
options.watermark
optional object
Watermark configuration container.
options.watermark.text
required in watermark object, string, max 120 chars
Watermark label text.
options.watermark.opacity
optional number, 0.02-0.6
Watermark alpha value.
options.watermark.rotation
optional number, -90 to 90
Rotation angle in degrees.
options.watermark.color
optional string, max 40 chars
Color token, for example a hex value.
Metadata
Set PDF document metadata fields
Use metadata to improve downstream indexing, compliance labeling, and document discoverability.
options.metadata
optional object
Metadata container for document properties.
options.metadata.title
optional string, max 255 chars
Document title.
options.metadata.author
optional string, max 255 chars
Document author.
options.metadata.subject
optional string, max 255 chars
Document subject line.
options.metadata.keywords
optional string[], up to 20 items, each max 255 chars
Keyword tags used by PDF readers and indexing systems.
options.metadata.creator
optional string, max 255 chars
Tool or workflow that created the source content.
options.metadata.producer
optional string, max 255 chars
Producer attribution for output generation.
Runtime and assets
Control script execution and protected asset fetches
Use these fields when rendering depends on JavaScript, strict CSP, or custom asset-fetch headers.
options.javascriptEnabled
optional boolean
Enables or disables page JavaScript execution.
options.csp
optional string, max 2000 chars
Inline Content-Security-Policy value for the render runtime.
options.assetHeaders
optional object of string headers
Additional request headers used while fetching protected assets.
Where this object appears
Render routes that consume the shared options object
Use this page for shared option fields and use rendering reference pages for full endpoint contracts.
Single render request body
POST /v1/pdf -> options
Use on HTML, URL, or template single render payloads.
Batch item request body
POST /v1/pdf/batch -> items[].options
Use for per-item option overrides in mixed batch inputs.
Next steps
Apply the shared options object in render flows
Need the single-route contract?
Open single render reference
Place options into one render request and combine it with input, output, and execution settings.
Need per-item overrides?
Open batch rendering reference
Apply items[].options across mixed inputs, progress tracking, downloads, and workflows that use webhooks.