PDF API

Navigate to a URL or render raw HTML and return a PDF file. Send either a url or an html field in the JSON body, but not both.

Endpoint

• Method: POST
• Path: /pdf
• Auth: token query parameter (?token=)
• Content-Type: application/json
• Response: application/pdf

See the OpenAPI reference for complete details.

Quickstart

cURL

curl -X POST \
  "https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "options": {
    "displayHeaderFooter": true,
    "printBackground": false,
    "format": "A0"
  }
}' \
  -o result.pdf

Javascript

import fs from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/pdf?token=${TOKEN}`;
const headers = {
  "Cache-Control": "no-cache",
  "Content-Type": "application/json"
};

const data = {
  url: "https://example.com/",
  options: {
    displayHeaderFooter: true,
    printBackground: false,
    format: "A0"
  }
};

const generatePDF = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const pdfBuffer = await response.arrayBuffer();
  await fs.writeFile("output.pdf", Buffer.from(pdfBuffer));
  console.log("PDF saved as output.pdf");
};

generatePDF();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/pdf?token={TOKEN}"
headers = {
    "Cache-Control": "no-cache",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com/",
    "options": {
        "displayHeaderFooter": True,
        "printBackground": False,
        "format": "A0"
    }
}

response = requests.post(url, headers=headers, json=data)

with open("output.pdf", "wb") as file:
    file.write(response.content)

print("PDF saved as output.pdf")

Response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="output.pdf"

<binary>

Examples

Setting HTML content

Use the html field to render inline HTML instead of navigating to a URL.

danger

When you send html, do not include url in the same request.

curl -X POST \
  "https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<h1>Hello World!</h1>",
  "options": {
    "displayHeaderFooter": true,
    "printBackground": false,
    "format": "A0"
  }
}' \
  -o result.pdf

Adding custom styles and scripts

Use addScriptTag and addStyleTag to inject scripts and styles before the PDF is generated.

curl -X POST \
  "https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE" \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "addScriptTag": [
    { "url": "https://code.jquery.com/jquery-3.7.1.min.js" },
    { "content": "document.querySelector(`h1`).innerText = `Hello World!`" }
  ],
  "addStyleTag": [
    {
      "content": "body { height: 100vh; background: linear-gradient(45deg, #da5a44, #a32784); }"
    },
    {
      "url": "https://interactive-examples.mdn.mozilla.net/live-examples/css-examples/text-decoration/text-decoration-color.css"
    }
  ]
}' \
  -o result.pdf

Fullpage PDF

The /pdf REST API doesn't support creating a single long-page PDF file that captures an entire webpage on one page. However, you can create custom full-page PDFs using our /function API.

The /function API gives you full control over the PDF generation process, allowing you to calculate the page height dynamically and format your PDF accordingly. This is particularly useful when you need to capture an entire webpage as a single continuous page rather than breaking it into multiple pages.

For a complete example of generating full-page PDFs, including code snippets in multiple languages, see the Returning files section in the /function API documentation.

PDF Metadata

Browserless's /pdf API uses Puppeteer under the hood to generate PDFs. By default, Puppeteer doesn't provide a built-in API to set PDF metadata (like Title, Author, Subject, Keywords, etc.) when generating a PDF with page.pdf().

Puppeteer relies on Chrome's printToPDF DevTools protocol, which only exposes a limited set of options (like page size, margins, header/footer, etc.), but not document metadata.

The workaround is to generate the PDF with Browserless first, then adjust the metadata with a library such as pdf-lib.

Configuration options

The /pdf API supports shared request configuration options that apply across REST endpoints:

• Waiting for things: Wait for events, functions, selectors, or timeouts before generating the PDF
• Navigation options: Customize navigation behavior with gotoOptions
• Rejecting undesired requests: Block resources with rejectResourceTypes and rejectRequestPattern
• Continue on error: Use bestAttempt to continue when async events fail or time out