⚡ REST API

PDF Conversion API
for Developers

Convert HTML, images, and documents to PDF with a single API call. Free tier included — no credit card required. Files are processed and immediately discarded.

Get Free API Key View Endpoints →

Quick Start

Get up and running in under 2 minutes. No SDK needed — just HTTP requests.

FASTEST PATH Minimum viable request — try this first

This is all you need. No options object required. Paste your API key and send it.

json — request body
{
  "html": "<h1>Hello World</h1><p>My first PDF!</p>"
}
json — response
{
  "success": true,
  "pdf": "JVBERi0xLjQ...",  // base64-encoded PDF bytes
  "pages": 1,
  "sizeBytes": 4821,
  "watermark": true,   // true on Free tier
  "usage": { "used": 1, "limit": 100, "remaining": 99 }
}

Decode the pdf field from base64 to get the raw PDF bytes.

1. Get your API key

Enter your email to generate a free API key instantly:

🎉 Your API key:

⚠ Save this key now — it cannot be retrieved later. Store it as an environment variable.

2. Make your first conversion

bash 
curl -X POST https://buildpdf.co/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "html": "<h1>Hello World</h1><p>My first PDF via API!</p>",
    "options": {
      "pageSize": "a4",
      "orientation": "portrait"
    }
  }'
javascript 
const response = await fetch('https://buildpdf.co/api/v1/convert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.BUILDPDF_API_KEY,
  },
  body: JSON.stringify({
    html: '<h1>Hello World</h1><p>My first PDF!</p>',
    options: { pageSize: 'a4' }
  })
});

const { pdf } = await response.json();
// pdf is a base64-encoded PDF — save it:
fs.writeFileSync('output.pdf', Buffer.from(pdf, 'base64'));
python 
import requests, base64, os

response = requests.post(
    "https://buildpdf.co/api/v1/convert",
    headers={"X-API-Key": os.environ["BUILDPDF_API_KEY"]},
    json={
        "html": "<h1>Hello World</h1><p>My first PDF!</p>",
        "options": {"pageSize": "a4"}
    }
)

pdf_bytes = base64.b64decode(response.json()["pdf"])
with open("output.pdf", "wb") as f:
    f.write(pdf_bytes)
php 
<?php
$ch = curl_init('https://buildpdf.co/api/v1/convert');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-API-Key: ' . getenv('BUILDPDF_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'html'    => '<h1>Hello World</h1>',
        'options' => ['pageSize' => 'a4'],
    ]),
]);
$result = json_decode(curl_exec($ch), true);
file_put_contents('output.pdf', base64_decode($result['pdf']));

Endpoints

POST /api/v1/convert

Convert HTML content, plain text, or image files (JPG, PNG) to PDF. Send one of html, text, or file — all other fields are optional.

ℹ HTML RENDERING NOTE

The current HTML renderer strips tags and outputs clean plain text — ideal for invoices, reports, and documents built with semantic HTML (<h1>, <p>, <ul>, <table>). Full CSS & layout rendering (fonts, colors, flexbox) is coming in v2. For styled HTML, use inline styles or the text field.

Request Body

ParameterTypeRequiredDescription
html string optional* HTML string to convert. Tags are parsed for structure; use <h1>–<h6>, <p>, <br>, <ul>, <ol> for best results. Max body size: 10 MB.
text string optional* Plain text string rendered directly to PDF. Line breaks and whitespace are preserved. Use this for logs, CSVs, or pre-formatted content.
file string optional* Base64-encoded image file (JPG or PNG). Must be paired with "format": "image". The image is scaled to fill the page while preserving aspect ratio.
format string optional Required when sending a file. Accepted value: "image" (JPG or PNG). Tells the API how to interpret the base64 payload.
options object optional PDF layout settings. All fields have sensible defaults — omit the entire object for a standard A4 portrait PDF.

* Provide exactly one of html, text, or file.

options Object Fields

FieldDefaultAccepted ValuesDescription
pageSize "a4" "a4", "letter", "a3", "legal" Output page dimensions. "a4" = 210×297mm (international). "letter" = 216×279mm (US standard).
orientation "portrait" "portrait", "landscape" Page orientation. "portrait" = tall (default). "landscape" = wide — good for tables and charts.
margin 10 Integer, 0–50 Page margin in millimeters applied to all four sides. Use 0 for edge-to-edge (full bleed). Use 20 for wide margins like a formal document.
quality 0.95 Float, 0.1–1.0 JPEG compression quality for image inputs only. 0.95 = high quality, larger file. 0.6 = smaller file, slight visual loss. Has no effect on text or HTML inputs.

Response

json
{
  "success": true,
  "pdf": "JVBERi0xLjQ...",  // base64-encoded PDF — decode to get raw bytes
  "pages": 2,             // number of pages in the generated PDF
  "sizeBytes": 18432,      // size of the PDF in bytes
  "watermark": true,      // true on Free tier, false on paid plans
  "usage": {
    "used": 1,            // conversions used this month
    "limit": 100,          // your plan's monthly limit
    "remaining": 99       // conversions left this month
  },
  "powered_by": "https://buildpdf.co"
}
POST /api/v1/extract

Extract the contents of a PDF file — get back either plain text or a ZIP of page images (JPG). Requires Starter plan or above.

ParameterTypeRequiredDescription
file string required Base64-encoded PDF file to extract from. Max size determined by your plan tier (Starter: 25 MB, Pro: 50 MB).
output string optional What to extract. "text" (default) returns a plain text string of all page content. "images" returns a base64-encoded ZIP file containing one JPG per page.
GET /api/v1/usage

Returns your current monthly usage, quota limit, and remaining conversions. This call does not count against your conversion quota — check it as often as you like.

POST /api/v1/register

Create a new free API key. Returns a bpdf_-prefixed key tied to your email. Each email address can hold one active key. Save the key immediately — it cannot be retrieved later.

ParameterTypeRequiredDescription
email string required Your email address. Used to associate your key with your account and prevent duplicate registrations. We do not send marketing emails.

Authentication

All API requests require an API key passed in the request header. Your key is prefixed with bpdf_. Keep it in an environment variable — never hardcode it in client-side code.

headers
# Option 1 (recommended): X-API-Key header
X-API-Key: bpdf_your_key_here

# Option 2: Authorization Bearer token
Authorization: Bearer bpdf_your_key_here

# Coming from RapidAPI? Use X-API-Key with your BuildPDF key,
# not the X-RapidAPI-Key. Your key starts with bpdf_

Live Playground

Test the API right here — enter your API key and HTML content to generate a PDF.

Try it out

Pricing

Start free. Upgrade when you need more. No credit card required for the free tier.

Free
$0/mo
100 conversions/mo
5 MB max file
10 req/min
"Powered by" watermark
HTML, Image, Text → PDF
Starter
$9/mo
1,000 conversions/mo
25 MB max file
60 req/min
No watermark
+ PDF Extraction
Pro
$29/mo
10,000 conversions/mo
50 MB max file
300 req/min
No watermark
+ Batch conversion
Business
$79/mo
50,000 conversions/mo
100 MB max file
1,000 req/min
Priority support
All features included

Error Codes

CodeMeaningWhat to do
400Bad RequestCheck your request body — a required field is missing or malformed.
401UnauthorizedAPI key is missing or invalid. Check the X-API-Key header.
403ForbiddenFeature not available on your tier. Upgrade your plan.
413File Too LargeFile exceeds your tier's size limit.
429Rate LimitedToo many requests. Wait and retry, or upgrade for higher limits.
500Server ErrorSomething went wrong on our end. Retry, or contact support.