API Documentation

Everything you need to integrate WebPDF.app into your projects.

Getting Started

WebPDF.app offers a simple REST API to convert HTML to PDF. Follow these steps to get started in less than 5 minutes.

1

Create an account

Sign up for free to get access to the dashboard.

2

Generate an API Key

From the dashboard, go to "API Keys" and create a new key.

3

Make your first request

Use your API Key to authenticate requests to the endpoint /v1/generate.

Quick Start - cURL
curl -X POST https://api.webpdf.app/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "YOUR_API_KEY", "url": "https://example.com"}' \
  --output document.pdf

Authentication

All API requests must include your API Key in the JSON request body.

API Key Authentication

Include the apiKey field in your JSON request body. Note: Currently, all keys are accepted for testing purposes.

Request Headers
{
  "apiKey": "wpdf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "url": "https://example.com"
}

Endpoint /generate

POST https://api.webpdf.app/v1/generate

Converts a web page or HTML content into a PDF document.

Request Body (JSON)

Parameter Type Description
apiKey string API Key for authentication (currently not validated)
url string URL of the web page to convert. Required if html is not provided.
html string Direct HTML content to convert. Required if url is not provided.
format string Page format: "Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A4", "A5", "A6" (default: "A4")
landscape boolean Page orientation: true for landscape, false for portrait (default: false)
marginTop integer Top margin in pixels (default: 0)
marginRight integer Right margin in pixels (default: 0)
marginBottom integer Bottom margin in pixels (default: 0)
marginLeft integer Left margin in pixels (default: 0)
width integer Custom page width in pixels (overrides format)
height integer Custom page height in pixels (overrides format)
media string CSS Media Type: "screen" or "print" (default: "screen")
Example Request
{
  "apiKey": "your-api-key-here",
  "url": "https://example.com",
  "format": "A4",
  "landscape": false,
  "marginTop": 10,
  "marginRight": 10,
  "marginBottom": 10,
  "marginLeft": 10,
  "media": "print"
}

Available Parameters

The following parameters can be sent in the JSON body of your POST request.

Parameter docs.options.type Default docs.options.description
format string "A4" Page format (Letter, Legal, Tabloid, Ledger, A0-A6)
width string - Custom page width in pixels (overrides format)
height string - Custom page height in pixels (overrides format)
landscape boolean false Page orientation: true for landscape, false for portrait
margin object 0 Margins (marginTop, marginRight, marginBottom, marginLeft)
printBackground boolean true CSS Media Type: "screen" or "print"
scale integer 1 Note: At least one of url or html must be provided. If both are provided, html is used.
displayHeaderFooter boolean false Show header and footer
headerTemplate string - HTML template for header
footerTemplate string - HTML template for footer
pageRanges string - Pages to include (e.g., "1-5, 8")
waitForSelector string - CSS selector to wait for before rendering
waitForTimeout integer 0 Additional milliseconds to wait

Code Examples

Copy and paste these examples to get started quickly in your preferred language.

// Node.js / JavaScript
const generatePdf = async () => {
  const response = await fetch('https://api.webpdf.app/v1/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      apiKey: process.env.WEBPDF_API_KEY,
      url: 'https://example.com',
      format: 'A4',
      landscape: false
    })
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`HTTP ${response.status}: ${errorText}`);
  }

  const pdfBuffer = await response.arrayBuffer();
  return Buffer.from(pdfBuffer);
};

// Usage
const pdf = await generatePdf();
fs.writeFileSync('output.pdf', pdf);
# Python
import requests
import os

def generate_pdf(url_to_convert):
    api_url = "https://api.webpdf.app/v1/generate"
    payload = {
        "apiKey": os.environ.get('WEBPDF_API_KEY'),
        "url": url_to_convert,
        "format": "A4",
        "landscape": False
    }
    headers = {"Content-Type": "application/json"}
    
    response = requests.post(api_url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.content
    else:
        print(f"Errore: {response.status_code} - {response.text}")
        return None

# Usage
pdf_bytes = generate_pdf("https://example.com")
if pdf_bytes:
    with open("output.pdf", "wb") as f:
        f.write(pdf_bytes)
// PHP
<?php

function generatePdf($url) {
    $apiKey = getenv('WEBPDF_API_KEY');
    
    $data = [
        'apiKey' => $apiKey,
        'url' => $url,
        'format' => 'A4',
        'landscape' => false
    ];
    
    $ch = curl_init('https://api.webpdf.app/v1/generate');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json'
        ]
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return $response;
}

// Usage
$pdf = generatePdf('https://example.com');
file_put_contents('output.pdf', $pdf);
// Java (with HttpClient)
import java.net.http.*;
import java.net.URI;

public class WebPdfClient {
    private static final String API_URL = "https://api.webpdf.app/v1/generate";
    private final String apiKey;
    
    public WebPdfClient(String apiKey) {
        this.apiKey = apiKey;
    }
    
    public byte[] generatePdf(String url) throws Exception {
        String json = String.format("{\"apiKey\":\"%s\",\"url\":\"%s\",\"format\":\"A4\"}", apiKey, url);
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(API_URL))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        
        HttpResponse response = client.send(
            request, HttpResponse.BodyHandlers.ofByteArray()
        );
        
        return response.body();
    }
}
// C# (.NET)
using System.Net.Http;
using System.Text;
using System.Text.Json;

public class WebPdfClient
{
    private readonly HttpClient _client;
    private readonly string _apiKey;
    private const string ApiUrl = "https://api.webpdf.app/v1/generate";

    public WebPdfClient(string apiKey)
    {
        _client = new HttpClient();
        _apiKey = apiKey;
    }

    public async Task<byte[]> GeneratePdfAsync(string url)
    {
        var payload = new {
            apiKey = _apiKey,
            url = url,
            format = "A4"
        };

        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await _client.PostAsync(ApiUrl, content);
        response.EnsureSuccessStatusCode();

        return await response.Content.ReadAsByteArrayAsync();
    }
}
# cURL con URL
curl -X POST https://api.webpdf.app/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "test-key",
    "url": "https://example.com",
    "format": "A4",
    "landscape": false
  }' \
  --output document.pdf

# cURL con HTML diretto
curl -X POST https://api.webpdf.app/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "test-key",
    "html": "

Test

PDF generato da HTML.

", "format": "A4" }'
\ --output document.pdf

Error Handling

The API returns standard HTTP codes and a JSON body with error details.

Code Meaning Action
200 Success PDF generated successfully
400 Bad Request Check request parameters
401 Unauthorized Missing or invalid API Key
403 Forbidden Insufficient credits or suspended account
429 Too Many Requests Rate limit exceeded, try again later
500 Server Error Internal error, contact us if persists

Rate Limits

To ensure service stability, we apply request limits per API Key.

Plan limits

  • Free 60 req/min
  • Startup 300 req/min
  • Business 600 req/min
  • Enterprise Custom

Response headers

  • X-RateLimit-Limit: Request limit per window
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Limit reset timestamp

Changelog

v3.0.0 - January 2024

Feature Update

  • Added support for html parameter
  • url parameter becomes conditional
  • Improved validation for required parameters
  • Backward compatibility maintained

v1.1.0 - June 2023

Initial Release

  • Initial endpoint /v1/generate
  • HTML to PDF conversion with iText 7
  • Automatic web content fetching
  • HTML cleaning with Jsoup
  • Support for existing PDFs (pass-through)

v1.0.0 - Jun 2023