html2pdfconverter API

Production-ready endpoints for HTML/URL → PDF, designed for servers and queues.

Public API

Base URL

https://api.html2pdfconverter.com

Authentication

Use your API key on all requests. This key is available in you dashboard settings

x-api-key: <YOUR_API_KEY>

Create Conversion Job

POST /convert

Method 1: JSON Body (Small files)

POST /convert
Content-Type: application/json
x-api-key: <YOUR_API_KEY>
{
  "url": "https://example.com/page",
  "options": {
    "format": "A4",
    "printBackground": true,
    "timeoutMs": 60000
  },
  "webhookUrl": "https://yourapp.com/webhooks/pdf"
}

Method 2: Multipart Upload (Large files)

curl -X POST "$BASE_URL/convert" \
  -H "x-api-key: $API_KEY" \
  -F "file=@document.html" \
  -F "options={"format":"A4","printBackground":true}"

File Size Limits by Plan:

  • • Free: 5MB | Starter: 10MB | Pro: 25MB
  • • Scale: 50MB | Enterprise: 100MB

Multipart uploads are streamed for optimal performance.

Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "jobId": "6a1c...f92",
  "status": "pending"
}

Poll /jobs/:job_id or supply webhookUrl to receive callbacks.

Check Job Status

GET /jobs/:job_id
GET /jobs/:job_id
x-api-key: <YOUR_API_KEY>
Response — completed
HTTP/1.1 200 OK
Content-Type: application/json

{
  "job_id": "6a1c...f92",
  "status": "completed",
  "downloadUrl": "https://s3...signed"
}
Response — failed
HTTP/1.1 200 OK
Content-Type: application/json

{
  "job_id": "6a1c...f92",
  "status": "failed",
  "errorMessage": "Rendering timeout"
}

Webhooks (optional)

If you send webhookUrl, we'll POST a signed JSON payload when the job finishes.

Authentication Header
X-PDF-Service-Signature: sha256=<hex>

Get your webhook secret from the customer portal dashboard.

Success payload

{
  "jobId": "<JOB_ID>",
  "status": "completed",
  "downloadUrl": "https://s3...signed",
  "renderTimeMs": 1234.56
}

Failure payload

{
  "jobId": "<JOB_ID>",
  "status": "failed",
  "error": "Rendering timeout"
}

Verification Example

const crypto = require('crypto');

function verifyWebhook(req, res) {
  const signature = req.headers['x-pdf-service-signature'];
  const secret = process.env.PDF_SERVICE_WEBHOOK_SECRET;
  
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');
  
  if (signature === expectedSignature) {
    console.log('✅ Webhook verified:', req.body);
  } else {
    res.status(401).send('Invalid signature');
  }
}

Code Examples

Here are code examples in various languages for creating PDF conversion jobs:

const fetch = require('node-fetch');

async function convertPdfNodeJs(sourceType, sourceContent, apiKey, webhookUrl = null) {
  const payload = {
    sourceType: sourceType, // "url" or "html"
    url: sourceType === "url" ? sourceContent : undefined,
    html: sourceType === "html" ? sourceContent : undefined,
    options: {
      format: "A4",
      printBackground: true,
      timeoutMs: 60000 // Optional
    },
    webhookUrl: webhookUrl // Optional
  };

  try {
    const response = await fetch('https://api.html2pdfconverter.com/convert', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.message || 'Failed to create conversion job');
    }

    const data = await response.json();
    console.log('Job created:', data);
    return data.jobId;
  } catch (error) {
    console.error('Error creating conversion job:', error);
    throw error;
  }
}

// Example usage:
// convertPdfNodeJs('url', 'https://example.com', 'YOUR_API_KEY', 'https://your-webhook-url.com');
// convertPdfNodeJs('html', '<h1>Hello World!</h1>', 'YOUR_API_KEY');

// For large files, use multipart upload:
async function convertPdfMultipart(filePath, apiKey) {
  const FormData = require('form-data');
  const fs = require('fs');
  const fetch = require('node-fetch');
  
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  form.append('options', JSON.stringify({ format: 'A4', printBackground: true }));
  
  const response = await fetch('https://api.html2pdfconverter.com/convert', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      ...form.getHeaders()
    },
    body: form
  });
  
  return await response.json();
}

Troubleshooting Timeouts

PDF conversion can sometimes time out, especially with complex content or slow-loading URLs. Here are some tips to avoid timeouts:

  • Optimize HTML/CSS: Keep your HTML clean, minimize large CSS files, and avoid unnecessary JavaScript.
  • Efficient Images: Use optimized image formats and sizes.
  • Fast URLs: If converting from a URL, ensure the target page loads quickly. Heavy client-side rendering or slow server responses can lead to timeouts.
  • Use Webhooks for long jobs: For jobs that might take longer than your plan's timeout, consider using the webhookUrl option to get an asynchronous notification when the job is complete. This avoids client-side request timeouts.
  • Adjust timeoutMs: You can specify options.timeoutMs in your /convert request. However, there's a maximum timeout enforced per plan. Refer to your dashboard for plan-specific limits.

AI Integrations (MCP)

You can integrate HTML2PDF Converter directly into your favorite AI tools (like Claude Desktop, Cursor, or other MCP-compatible clients) using our official Model Context Protocol (MCP) server.

This allows your AI to natively generate PDFs and save them to your computer without you having to write any code.

Installation via npx

npx -y @html2pdfconverter/mcp-server

Claude Desktop Configuration

Add the following to your claude_desktop_config.json file:

{
  "mcpServers": {
    "html2pdf": {
      "command": "npx",
      "args": ["-y", "@html2pdfconverter/mcp-server"],
      "env": {
        "HTML2PDF_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Note: Replace YOUR_API_KEY_HERE with a real API key generated from your dashboard.