Converting HTML

The core of pdfRelay is the synchronous conversion endpoint. Send HTML in, get a PDF back.

Endpoint

POST https://api.pdfrelay.com/v1/convert

Request Body

Send a JSON body with your content source and optional configuration:

HTML source

{
  "source": "html",
  "content": "<html><body><h1>Invoice #1234</h1></body></html>",
  "options": {
    "page_size": "A4",
    "orientation": "portrait",
    "margins": {
      "top": "20mm",
      "bottom": "20mm",
      "left": "15mm",
      "right": "15mm"
    },
    "header_html": "<div style='text-align:center;font-size:10px'>Page {{page}} of {{pages}}</div>",
    "footer_html": "<div style='text-align:center;font-size:10px'>Confidential</div>"
  }
}

URL source

Pass a public URL instead of raw HTML:

{
  "source": "url",
  "url": "https://example.com/report",
  "options": {
    "page_size": "Letter"
  }
}

Options Reference

Parameter	Type	Default	Description
`page_size`	string	`"Letter"`	Page size: Letter, A4, A3, Legal, Tabloid
`orientation`	string	`"portrait"`	"portrait" or "landscape"
`margins.top`	string	`"10mm"`	Top margin (mm, in, cm, px)
`margins.bottom`	string	`"10mm"`	Bottom margin
`margins.left`	string	`"10mm"`	Left margin
`margins.right`	string	`"10mm"`	Right margin
`header_html`	string	`null`	HTML for page header. Supports {{page}} and {{pages}} placeholders.
`footer_html`	string	`null`	HTML for page footer
`encrypt`	boolean	`false`	Enable AES-256 PDF encryption
`user_password`	string	`null`	Password required to open the PDF
`owner_password`	string	`null`	Password for full access (editing, printing)
`no_print`	boolean	`false`	Restrict printing when encrypted
`no_copy`	boolean	`false`	Restrict text copying when encrypted
`no_modify`	boolean	`false`	Restrict modification when encrypted
`pdf_profile`	string	`null`	"pdf-a-3b" for archival, "pdf-ua" for accessibility
`tagged`	boolean	`false`	Generate tagged/accessible PDF

Response Format

JSON response (default)

By default, the API returns a JSON envelope with metadata and a download URL:

{
  "id": "conv_r8Kx2mNpQw",
  "status": "completed",
  "document_id": "doc_4f7a1b2c",
  "page_count": 1,
  "duration_ms": 94,
  "download_url": "/v1/documents/doc_4f7a1b2c/download"
}

Raw PDF binary

Set the Accept header to application/pdf to receive the PDF file directly:

curl -X POST https://api.pdfrelay.com/v1/convert \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/pdf" \
  -d '{"source": "html", "content": "<h1>Hello</h1>"}' \
  -o output.pdf

Document Hosting

Add a hosting object to generate a public download link with optional download limits, expiration, and password protection.

{
  "source": "html",
  "content": "<h1>Hosted Invoice</h1>",
  "hosting": {
    "enabled": true,
    "download_limit": 10,
    "expires_in": 86400,
    "password": "secret123"
  }
}

See Options & Hosting for the full reference.

Test Mode

Add "test": true to your request to generate a watermarked PDF that doesn't count against your quota. Test mode is unlimited on all plans.

{
  "source": "html",
  "content": "<h1>Draft Invoice</h1>",
  "test": true
}