Getting Started

PdfKong API

PdfKong is a REST API that returns a high-fidelity PDF file. You can use a URL, HTML source, Markdown, or Office documents with multiple modifiers to create your PDF. The file can then be downloaded directly, or we can upload it to your S3 bucket and notify you with webhooks. This can be done with basically any programming language in both browser and server environments.

Powered by headless Chromium engines managed in Gotenberg clusters, our system is completely stateless—processed in-memory with zero disk write activities, guaranteeing top-tier security and full GDPR compliance.

Setup Guide

Follow these steps to integrate PdfKong into your workflow.

Sign Up

Sign up for an account on our platform. This will give you access to your API key, which is necessary for making requests to the API.

Learn more about authentication →

Test the API

Test the API by making a simple request using your API key and a sample URL. You can use a tool such as Postman, cURL, or our Playground.

Integrate

Integrate the API into your application. We offer a wide variety of options to customize the generated PDF files, such as page size, orientation, margins, headers, footers, and more.

curl -X POST "https://api.pdfkong.com/v1/convert" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "mode": "url", "url": "https://example.com", "async": true, "page_size": "A4", "orientation": "landscape" }' \ --output document.pdf

<?php $response = Http::withToken('YOUR_API_KEY') ->post('https://api.pdfkong.com/v1/convert', [ 'mode' => 'url', 'url' => 'https://example.com', 'async' => true, 'page_size' => 'A4', 'orientation' => 'landscape' ]); file_put_contents('document.pdf', $response->body());

const fs = require('fs'); fetch('https://api.pdfkong.com/v1/convert', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, body: JSON.stringify({ mode: 'url', url: 'https://example.com', async: true, page_size: 'A4', orientation: 'landscape' }) }) .then(res => res.buffer()) .then(buffer => fs.writeFileSync('document.pdf', buffer));

import requests response = requests.post( 'https://api.pdfkong.com/v1/convert', headers={ 'Authorization': 'Bearer YOUR_API_KEY' }, json={ 'mode': 'url', 'url': 'https://example.com', 'async': True, 'page_size': 'A4', 'orientation': 'landscape' } ) with open('document.pdf', 'wb') as f: f.write(response.content)

Core Processing Services & Parameters

Explore all available configuration parameters categorized by functionality. Pay attention to the Supported Modes column to know which modifiers work with your chosen mode.

Delivery

Parameter	Description	Supported Modes	Default
`delivery_mode`	Specifies the response output flow mechanism: inline, attachment, json, base64, s3, webhook, jsonp. Note: In JSON and Webhook modes, files are temporarily stored for 24 hours to allow downloading. In all other modes, files are processed strictly in-memory and are never stored on our servers.	All Modes	`json`
`callback`	Function name for the jsonp delivery mode.	html url office markdown	empty
`webhook_endpoint`	Webhook URL callback endpoint.	All Modes	empty
`s3_bucket_name`	Amazon S3 target bucket name.	All Modes	empty
`s3_bucket_key`	AccessKeyID of your S3 bucket.	All Modes	empty
`s3_bucket_secret`	Secret of your S3 bucket.	All Modes	empty
`s3_region`	Amazon S3 bucket service region.	All Modes	`us-east-1`
`s3_path`	Custom folder upload sub-path key.	All Modes	`documents`
`gcp_project_id`	Your Google Cloud Platform Project ID.	All Modes	empty
`gcp_user_email`	The email address of your GCP service account.	All Modes	empty
`gcp_private_key`	The private key associated with your GCP service account.	All Modes	empty
`gcp_bucket_name`	The name of your target Google Cloud Storage bucket.	All Modes	empty

Filters

Parameter	Description	Supported Modes	Default
`no_images`	Set to true in order to disable images.	html batch markdown	false
`no_links`	Set to true in order to disable links.	html batch markdown	false
`no_backgrounds`	Set to true in order to disable background graphics and colors.	html url batch markdown	false
`no_javascript`	Set to true in order to disable javascript execution.	html	false
`no_blank_pages`	Set to true in order to remove blank pages.	html batch markdown	false
`no_css`	Set to true in order to disable css.	html	false
`no_ads`	Set to true in order to remove ads.	html	false
`no_forms`	Set to true in order to disable forms.	html	false

General Configuration

Parameter	Description	Supported Modes	Default
`mode`	The core processing mode for your conversion. Defines the type of source material you are converting. Can be inferred automatically in some cases, but highly recommended to set explicitly.	All Modes	`html`
`url`	The website URL to capture and convert to PDF. Note: Mutually exclusive with html.	url	empty
`file`	The file to be converted (e.g., .docx, .xlsx, .pptx). Required for Office mode.	office	empty
`html`	Raw HTML content to render into a PDF document. Note: Mutually exclusive with url.	html batch	`<!DOCTYPE html> <html lang="en"> <hea...`
`markdown`	Raw Markdown content to render into a PDF document. Note: Mutually exclusive with html and url.	markdown batch	`# Invoice Date: {{ date \| defaul...`
`filename`	Specify a custom filename for the generated PDF. Max: 180 chars. Value "random" generates a random name.	html url office markdown	`random`
`js`	JS code or URL to inject as a script tag in the head section.	html batch markdown	`// Change title text and color docume...`
`css`	CSS markup or URL to inject as a style/link tag in the head section.	html batch markdown	`body { font-family: 'Helvetica Ne...`
`parse_liquid`	Enable standard Liquid template parser for parsing dynamic loops and variables within the HTML code.	html batch markdown	false
`liquid_data`	JSON structured key-value variables to replace dynamic tags when parse_liquid is true.	html batch markdown	`{ "customer_name": "Acme Corp", ...`
`secret_key`	Token used to verify a request that is locked to a domain or specific html.	All Modes	empty
`enable_html_validation`	Automatically check if the HTML is valid and well-formed (checks tag nesting and closing tags).	html batch	false

General Options

Parameter	Description	Supported Modes	Default
`sandbox`	Runs PDF generation in sandbox dry-run mode.	All Modes	false

HTTP Config

Parameter	Description	Supported Modes	Default
`user_agent`	Set to your preferred User-Agent header string.	html url batch markdown	empty
`accept_language`	Set to your preferred Accept-Language header string.	html url batch markdown	`en-US`
`accept_encoding`	Set to your preferred text encoding string.	html url batch markdown	`utf-8`
`auth_user`	Username value for accessing password protected content.	html url batch markdown	empty
`auth_password`	Password value for accessing password protected content.	html url batch markdown	empty
`http_cookies`	JSON object with key and value of cookies that will be sent to the URL source.	html url batch markdown	`{ "session_id": "123456789" }`
`http_headers`	JSON object with key and value of http headers that will be sent to the URL source.	html url batch markdown	`{ "X-Custom-Header": "MyValue" }`

Headers & Footers

Parameter	Description	Supported Modes	Default
`header_html`	HTML template content for page headers.	html url batch markdown	`<div style="font-size: 10px; text-ali...`
`header_text`	Standard raw text to print in the page header.	html url batch markdown	empty
`header_align`	Alignment property of the header content.	html url batch markdown	`left`
`header_margin`	Margin at the top of the page for the header placement.	html url batch markdown	`0px`
`footer_html`	HTML template content for page footers.	html url batch markdown	`<div style="font-size: 9px; text-alig...`
`footer_text`	Standard raw text to print in the page footer.	html url batch markdown	empty
`footer_align`	Alignment property of the footer content.	html url batch markdown	`right`
`footer_margin`	Margin at the bottom of the page for the footer placement.	html url batch markdown	`0px`

Image Compression

Parameter	Description	Supported Modes	Default
`image_compression_quality`	Quality of the images in the pdf. Between 0 and 100. 0 is the lowest quality and 100 is the highest quality. Images get compressed in the server and then injected in the pdf to reduce the file size.	html url batch markdown	empty
`image_compression_width`	Images wider than the image_compression_width will be resized to the image_compression_width. Images get compressed in the server and then injected in the pdf to reduce the file size. Resized images also get compressed.	html url batch markdown	empty

Location

Parameter	Description	Supported Modes	Default
`location_accuracy`	Sets the accuracy of the browser location (0-100).	html batch markdown	`100`
`location_lat`	Sets the latitude of the browser location (-90 to 90 degrees).	html batch markdown	empty
`location_lng`	Sets the longitude of the browser location (-180 to 180 degrees).	html batch markdown	empty

Margins

Parameter	Description	Supported Modes	Default
`margin_top`	Margin at the top of the page in mm, cm, in, px or pt.	html url batch markdown	`0px`
`margin_bottom`	Margin at the bottom of the page in mm, cm, in, px or pt.	html url batch markdown	`0px`
`margin_left`	Margin at the left of the page in mm, cm, in, px or pt.	html url batch markdown	`0px`
`margin_right`	Margin at the right of the page in mm, cm, in, px or pt.	html url batch markdown	`0px`

Page Setup

Parameter	Description	Supported Modes	Default
`page_size`	Standard paper format. ISO A-series: A0–A9. ISO B-series: B0–B9. Named: C5E, Comm10E, DLE, Executive, Folio, Ledger, Legal, Letter, Tabloid. Use "Custom" with page_width + page_height for any arbitrary size.	html url batch markdown	`A4`
`page_width`	Page width in mm, cm, in, px or pt.	html url batch markdown	empty
`prefer_css_page_size`	Force the use of page size defined by CSS (@page { size: ... }) instead of the page_size parameter.	html url batch markdown	false
`generate_document_outline`	Embed the document outline (bookmarks) into the PDF based on the HTML heading tags (h1, h2, etc.).	html url batch markdown	false
`page_height`	Page height in mm, cm, in, px or pt.	html url batch markdown	empty
`orientation`	Sets the orientation of the created pdf document: vertical (portrait) or horizontal (landscape).	html url batch markdown	`vertical`
`use_print_media`	Set to true in order to activate CSS @media print declarations.	html url batch markdown	false
`viewport`	Viewport size to render your html in (e.g. 1440x900).	html url batch markdown	`1440x900`
`zoom`	Adjust the HTML zoom factor.	html batch markdown	`1`
`print_pages`	Pages to print. Can be single number (3), range (1-5), list (4,5,6) or mixed (1-3,6).	html url batch markdown	empty

Security & Metadata

Parameter	Description	Supported Modes	Default
`title`	Sets the title meta tag of the created pdf file.	All Modes	empty
`author`	Sets the author meta tag of the created pdf file.	All Modes	empty
`creator`	Sets the creator meta tag of the created pdf file.	All Modes	`PDFKong`
`producer`	Sets the producer meta tag of the created pdf file.	All Modes	`PDFKong`
`subject`	Sets the subject meta tag of the created pdf file.	All Modes	empty
`keywords`	Sets the keyword meta tag. Multiple keywords separated with a comma.	All Modes	empty
`encrypt`	Set to true to encrypt the generated pdf file.	All Modes	false
`owner_password`	Password of the pdf owner.	All Modes	empty
`user_password`	Password for the user that will view the pdf.	All Modes	empty
`encryption_print_rights`	Sets the rights of who can print the pdf: none, low, full.	All Modes	`full`
`encryption_modify_rights`	Sets the rights of who can modify the pdf.	All Modes	`all`
`encryption_copy_rights`	Sets the rights of who can copy the pdf.	All Modes	`full`

Wait & Render

Parameter	Description	Supported Modes	Default
`wait_for_selector`	Will wait until the CSS selector is present in html. Use # for id and . for className.	html url batch markdown	empty
`wait_for_function`	String of the function name that should be executed and waited for until it returns a result.	html url batch markdown	empty
`wait_for_timeout`	In milliseconds. Will wait for this duration before creating the pdf.	html url batch markdown	empty
`scroll_whole_page`	Scroll the whole page and load all images before rendering the pdf.	html url batch markdown	false

Watermark

Parameter	Description	Supported Modes	Default
`watermark`	Enable watermark overlays.	All Modes	false
`watermark_text`	The watermark overlay text phrase.	All Modes	`CONFIDENTIAL`
`watermark_img`	Https URL or base64 encoded image for image watermark.	All Modes	empty
`watermark_font_size`	Font size of the text of the watermark.	All Modes	`48`
`watermark_font_family`	CSS font-family for the text in the watermark. Can automatically load Google Fonts.	All Modes	`sans-serif`
`watermark_font_color`	Color of the watermark font (HEX or CSS name).	All Modes	`#cccccc`
`watermark_font_bold`	Set to true to make the watermark text bold.	All Modes	false
`watermark_font_italic`	Set to true to make the text style italic.	All Modes	false
`watermark_img_width`	Width of the watermark in mm, cm, in, px or pt.	All Modes	empty
`watermark_img_height`	Height of the watermark in mm, cm, in, px or pt.	All Modes	empty
`watermark_rotate`	Used to rotate the watermark.	All Modes	`-45`
`watermark_opacity`	Set the opacity percentage of the watermark (0-100).	All Modes	`20`
`watermark_offset_x`	Offset used to horizontally align a watermark.	All Modes	`0px`
`watermark_offset_y`	Offset used to vertically align a watermark.	All Modes	`0px`
`watermark_in_background`	Set to true in order to place watermark images/text in the background.	All Modes	false