PDFSpark API Documentation

Convert HTML and URLs to pixel-perfect PDFs using Chromium with full JavaScript, CSS3, and web font rendering. The API is completely free — no API keys, no authentication, no signup.

Base URL: https://pdfspark.dev/api/v1

Authentication

No authentication is required. Simply make HTTP requests to the endpoints below. All responses return the PDF binary directly (application/pdf).

POST /pdf/from-html

POST /api/v1/pdf/from-html

Convert raw HTML content to PDF. Supports inline CSS, JavaScript, images via data URIs or external URLs, and web fonts.

Request Body (JSON)

Field	Type	Required	Description
`html`	string	required	The HTML content to convert (max 5MB)
`options`	object	optional	PDF generation options (see Options)

Example Request

          
          
          
          cURL
        
curl -X POST "https://pdfspark.dev/api/v1/pdf/from-html" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Hello World</h1><p>Generated by PDFSpark</p>",
    "options": {
      "format": "A4",
      "margin": { "top": "20mm", "bottom": "20mm" }
    }
  }' \
  -o document.pdf

Response

Returns the PDF file directly as application/pdf binary. Use -o filename.pdf in cURL to save it.

POST /pdf/from-url

POST /api/v1/pdf/from-url

Convert a public webpage to PDF. The URL is loaded in Chromium with full JavaScript execution, just like a real browser.

Request Body (JSON)

Field	Type	Required	Description
`url`	string	required	The URL to convert (must be http/https, no private IPs)
`options`	object	optional	PDF generation and navigation options (see Options)

Example Request

          
          
          
          cURL
        
curl -X POST "https://pdfspark.dev/api/v1/pdf/from-url" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "format": "A4",
      "printBackground": true,
      "waitUntil": "networkidle"
    }
  }' \
  -o example.pdf

GET /status

GET /api/v1/status

Returns service status and available endpoints.

          
          
          
          Response
        
{
  "service": "PDFSpark",
  "version": "1.0.0",
  "status": "operational",
  "endpoints": [
    { "method": "POST", "path": "/api/v1/pdf/from-html" },
    { "method": "POST", "path": "/api/v1/pdf/from-url" },
    { "method": "GET", "path": "/api/v1/status" }
  ]
}

Page Format Options

Option	Type	Default	Description
`format`	string	`"A4"`	Page format: `A3`, `A4`, `A5`, `Letter`, `Legal`, `Tabloid`
`width`	string	—	Custom page width (e.g. `"8.5in"`). Overrides format.
`height`	string	—	Custom page height (e.g. `"11in"`). Overrides format.
`landscape`	boolean	`false`	Landscape orientation
`printBackground`	boolean	`true`	Print background graphics and colors
`scale`	number	`1`	Scale factor (0.1 to 2.0)
`pageRanges`	string	`""`	Page ranges to print (e.g. `"1-3, 5"`)
`preferCSSPageSize`	boolean	`false`	Use CSS `@page` size instead of format

Margin Options

Option	Type	Default	Description
`margin.top`	string	`"10mm"`	Top margin (CSS units: mm, in, px, cm)
`margin.right`	string	`"10mm"`	Right margin
`margin.bottom`	string	`"10mm"`	Bottom margin
`margin.left`	string	`"10mm"`	Left margin

Header & Footer Options

Option	Type	Default	Description
`displayHeaderFooter`	boolean	`false`	Enable header and footer
`headerTemplate`	string	`""`	HTML template for header. Supports: `date`, `title`, `url`, `pageNumber`, `totalPages`
`footerTemplate`	string	`""`	HTML template for footer (same classes as header)

Header/footer templates use special CSS classes: , , , , .

Option	Type	Default	Description
`waitUntil`	string	`"domcontentloaded"`	`load`, `domcontentloaded`, or `networkidle`
`waitForSelector`	string	—	Wait for a CSS selector to appear before PDF generation
`delay`	number	`0`	Additional delay in ms after page load (max 10000)
`timeout`	number	`30000`	Navigation timeout in ms (max 60000)
`css`	string	—	Custom CSS to inject before PDF generation
`javascript`	boolean	`true`	Enable/disable JavaScript execution
`viewport.width`	number	`1280`	Viewport width in pixels
`viewport.height`	number	`720`	Viewport height in pixels

Error Codes

Status	Meaning
`400`	Bad Request — Missing or invalid input (HTML, URL, or options)
`404`	Not Found — Endpoint does not exist
`413`	Payload Too Large — HTML exceeds 5MB limit
`429`	Too Many Requests — Rate limit exceeded (20/min)
`500`	Internal Server Error — PDF generation failed
`503`	Service Unavailable — Server busy (too many concurrent requests)

Error responses are JSON:

          
          Error Response
        
{
  "error": "Missing HTML",
  "message": "Provide an \"html\" field in the request body"
}

Rate Limits

Limit	Value
Requests per minute	`20` per IP address
Max concurrent PDFs	`5` server-wide
Max HTML size	`5MB`
Navigation timeout	`60s` max

Rate limit headers are included in every response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

cURL Examples

          
          
          
          terminal
        
# Convert HTML to PDF
curl -X POST "https://pdfspark.dev/api/v1/pdf/from-html" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Invoice #1234</h1><p>Total: $99.00</p>"}' \
  -o invoice.pdf

# Convert URL to PDF (landscape A3)
curl -X POST "https://pdfspark.dev/api/v1/pdf/from-url" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com",
    "options": { "format": "A3", "landscape": true }
  }' \
  -o github.pdf

JavaScript Example

          
          
          
          app.js
        
// Convert HTML to PDF
const response = await fetch('https://pdfspark.dev/api/v1/pdf/from-html', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    html: '<h1>Hello World</h1><p>From PDFSpark</p>',
    options: { format: 'A4', margin: { top: '20mm', bottom: '20mm' } }
  })
});

const blob = await response.blob();
const url = URL.createObjectURL(blob);
window.open(url); // or save with a download link

// Convert URL to PDF
const urlResponse = await fetch('https://pdfspark.dev/api/v1/pdf/from-url', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com' })
});

const pdfBlob = await urlResponse.blob();
// Use pdfBlob as needed...

Python Example

          
          
          
          main.py
        
import requests

# Convert HTML to PDF
response = requests.post(
    'https://pdfspark.dev/api/v1/pdf/from-html',
    json={
        'html': '<h1>Invoice #1234</h1><p>Total: $99.00</p>',
        'options': {'format': 'A4', 'printBackground': True}
    }
)

with open('invoice.pdf', 'wb') as f:
    f.write(response.content)

# Convert URL to PDF
response = requests.post(
    'https://pdfspark.dev/api/v1/pdf/from-url',
    json={'url': 'https://example.com'}
)

with open('example.pdf', 'wb') as f:
    f.write(response.content)

PDFSpark API Documentation

Authentication

POST /pdf/from-html

Request Body (JSON)

Example Request

Response

POST /pdf/from-url

Request Body (JSON)

Example Request

GET /status

Page Format Options

Margin Options

Header & Footer Options

Navigation Options (URL mode)

Error Codes

Rate Limits

cURL Examples

JavaScript Example

Python Example