On this page ▾

API Reference

RapidPDF API Documentation

RapidPDF converts HTML content or public URLs into PDFs via a simple REST API. Generate invoices, reports, certificates, and any document — in milliseconds.

Base URL

https://api.rapidpdf.io/api/v1

Content Type

application/json

X-API-Key

API key authentication

All RapidPDF API requests are authenticated with an API key passed via the X-API-Key header. Create keys from your dashboard.

Authentication

RapidPDF uses API key authentication. Create an API key in your dashboard and pass it via the X-API-Key header on every request. Never expose keys in client-side code.

API Key headerbash

X-API-Key: rpdf_xxxxxxxxxxxxxxxxxxxx

⚠️

API keys are shown once at creation time. Store them securely — they cannot be retrieved again. Rotate immediately if exposed.

Endpoints

Generate PDF

POST/api/v1/generate

Convert HTML content or a URL to a PDF. Requires an API key. Returns a JSON envelope with a pre-signed S3 URL plus performance timing headers. Usage is tracked asynchronously per key.

ℹ️

Exactly one of htmlContent or url must be provided — not both, not neither.

ℹ️

Requires X-API-Key header. Rate limited to 100 requests per 60 seconds per key. Exceeding this returns 429.

Request body

Parameter	Type	Required	Description
htmlContent	string	required	HTML string to render. 10–1,000,000 characters. Required if url is not provided.
url	string	optional	Public URL to navigate to and render. Required if htmlContent is not provided.
pdfOptions.format	string	optional	Page format: Letter, Legal, Tabloid, Ledger, A0–A6. Default: A4.
pdfOptions.landscape	boolean	optional	Landscape orientation. Default: false.
pdfOptions.margin	object	optional	Page margins — top, right, bottom, left as CSS length strings (e.g. "1cm").

Example request

cURLbash

curl -X POST https://api.rapidpdf.io/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rpdf_xxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "htmlContent": "<h1 style=\"font-family:sans-serif\">Invoice #1042</h1>",
    "pdfOptions": {
      "format": "A4",
      "landscape": false,
      "printBackground": true,
      "margin": { "top": "2cm", "bottom": "2cm", "left": "1.5cm", "right": "1.5cm" }
    }
  }'

Performance response headers

Header	Value
Server-Timing	pdf;dur=800, s3;dur=300, total;dur=1100
X-Perf-Pdf-Generation-Ms	PDF render duration in ms
X-Perf-S3-Upload-Ms	S3 upload duration in ms
X-Perf-Total-Ms	Total end-to-end request duration in ms

Response

Field	Type	Description
success	boolean	Always true on 200.
data.id	string	Unique filename of the generated PDF.
data.url	string	Pre-signed S3 URL valid for 24 hours.
data.expiresAt	ISO 8601 date	Expiry timestamp for the signed URL.
data.size_bytes	number	File size of the generated PDF in bytes.
message	string	Human-readable status message.

200 OKjson

{
  "success": true,
  "data": {
    "id": "1737048457123.pdf",
    "url": "https://your-bucket.s3.amazonaws.com/files/1737048457123.pdf?X-Amz-...",
    "expiresAt": "2026-05-07T10:24:17.123Z",
    "size_bytes": 48230
  },
  "message": "PDF generated successfully"
}

Health Check

GET/api/v1/health

Returns the current health of the API and its dependencies (MongoDB, Redis). Use for uptime monitoring. This endpoint does not require an API key — it is mounted on the public router so monitoring tools can reach it without authentication.

200 OKjson

{
  "status": "OK",
  "message": "API and dependencies are healthy",
  "checks": {
    "api": true,
    "mongodb": { "ok": true, "state": 1 },
    "redis": { "ok": true }
  },
  "timestamp": "2026-05-17T10:00:00.000Z"
}

503 Service Unavailablejson

{
  "status": "DEGRADED",
  "message": "One or more dependencies are unavailable",
  "checks": {
    "api": true,
    "mongodb": { "ok": false, "state": 0 },
    "redis": { "ok": true }
  },
  "timestamp": "2026-05-17T10:00:00.000Z"
}

PDF Options Reference

Pass any of these inside the pdfOptions object on either PDF endpoint. All fields are optional.

Option	Type	Default	Notes
format	string	"A4"	Letter, Legal, Tabloid, Ledger, A0–A6.
landscape	boolean	false	Rotate page to landscape orientation.
printBackground	boolean	true	Render CSS background colors and images.
scale	number	1	Page scale factor. Range: 0.1–2.0.
margin.top	string	"1cm"	Top margin. Any CSS length (px, cm, mm, in).
margin.right	string	"1cm"	Right margin.
margin.bottom	string	"1cm"	Bottom margin.
margin.left	string	"1cm"	Left margin.
media	string	"screen"	CSS media type. Use "print" for @media print styles.
width	string	—	Custom page width, overrides format (e.g. "210mm").
height	string	—	Custom page height, overrides format.

Full pdfOptions example

pdfOptions objectjson

{
  "pdfOptions": {
    "format": "A4",
    "landscape": false,
    "printBackground": true,
    "scale": 1,
    "margin": {
      "top": "2cm",
      "right": "1.5cm",
      "bottom": "2cm",
      "left": "1.5cm"
    },
    "media": "print"
  }
}

💡

For pixel-perfect rendering, use media: "print" if your HTML has @media print styles. Use media: "screen" (the default) to render what a user sees in the browser.

Error Reference

All errors follow a consistent JSON envelope. Validation errors include a per-field errors array.

Standard error responsejson

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "htmlContent", "message": "String must contain at least 10 character(s)" }
  ]
}

Status	Error class	When it occurs
400	BadRequestError / ValidationError	Malformed request, failed Zod validation, or HTML > 500 KB.
401	UnauthorizedError	Missing or invalid API key.
403	ForbiddenError	Valid key but insufficient permissions.
422	UnprocessableEntityError	Both url and htmlContent omitted.
429	TooManyRequestsError	Rate limit exceeded. Respect Retry-After header.
500	InternalServerError	Unexpected server error. Reported to Sentry.
503	ServiceUnavailableError	MongoDB or Redis dependency unavailable.

Rate Limits

RapidPDF uses Redis-backed rate limiting. The generate endpoint is limited per API key.

Route group	Limit	Window	Block duration
API key generate endpoint	100 req	60 s	5 min

Rate limit response headers

Header	Description
RateLimit-Limit	Maximum requests allowed in the current window.
X-RateLimit-Remaining	Requests remaining before the limit resets.
X-RateLimit-Reset	Unix timestamp (ms) when the window resets.

429 Too Many Requestsjson

{
  "success": false,
  "message": "Too Many Requests",
  "retryAfter": 42
}

⚠️

When you receive a 429, wait retryAfter seconds before retrying. Continued requests during a block period will extend the block.

Interactive Playground

Test the authenticated PDF generator with your own API key. Paste your key, edit the request body, and click Run to hit /api/v1/generate and generate a real PDF.

POST/api/v1/generate

X-API-Key

Request body

Response

Click Run to generate a PDF…

Tests run against /api/v1/generate with the API key you provide.