HTML to PDF API

Convert html, htm files to pdf with a single POST request. Upload a file as multipart/form-data and the API returns a download URL for the converted file.

Try it online Read the guide

Input

html, htm

Output

pdf (application/pdf)

Credit cost

2 per file

Max file size

Per plan (10–500 MB)

Endpoint

POSThttps://api.fileswitch.co/api/v1/converter/html-to-pdf

Authentication is optional for guests and recommended for production. Send either an API key or a JWT access token as a Bearer token. Authenticated requests deduct 2 credits from your balance; failed conversions are refunded. See Authentication for details.

Quick start

The same request in every supported language. Each example uploads a file and prints the downloadUrl from the response.

Example request

curl -X POST https://api.fileswitch.co/api/v1/converter/html-to-pdf \
  -H "Authorization: Bearer fc_YOUR_API_KEY" \
  -F "file=@input.html" \
  -F "pageSize=A4" \
  -F "pageWidthMm=0" \
  -F "pageHeightMm=0" \
  -F "printBackground=true" \
  -F "marginTop=20px" \
  -F "marginRight=20px" \
  -F "marginBottom=20px" \
  -F "marginLeft=20px" \
  -F "conversionDelay=0" \
  -F "waitForElementTimeout=30000" \
  -F "javascriptEnabled=true" \
  -F "viewportWidth=1366" \
  -F "viewportHeight=1024" \
  -F "cssMediaType=screen" \
  -F "scale=1"

Parameters

Send file plus any optional options. Every option is optional and falls back to its default when omitted.

Field	Type	Default	Description
file	binary	—	The file to convert. Accepts `.html , .htm`
pageSize	string	A4	Output page size. Overridden by pageWidthMm/pageHeightMm when set. Values: A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, B0, B1, B2, B3, B4, B5, Letter, Legal, Ledger, Tabloid
pageWidthMm	number	0	Custom page width in millimeters. 0 = use pageSize. Range: 0 .. 30000
pageHeightMm	number	0	Custom page height in millimeters. 0 = use pageSize. Range: 0 .. 30000
landscape	boolean	false	Render the page in landscape orientation.
printBackground	boolean	true	Print the CSS background graphics.
marginTop	string	20px	Top margin as a CSS length (e.g. 20px, 12mm).
marginRight	string	20px	Right margin as a CSS length.
marginBottom	string	20px	Bottom margin as a CSS length.
marginLeft	string	20px	Left margin as a CSS length.
headerText	string	—	Repeated on every page header. Use headerHtml for styled or dynamic headers.
footerText	string	—	Repeated on every page footer. Use footerHtml for styled or dynamic footers.
headerHtml	string	—	HTML header inserted on every page. Spans with classes pageNumber, totalPages, title, and date are auto-filled (see example below). Takes precedence over headerText.
footerHtml	string	—	HTML footer inserted on every page. Spans with classes pageNumber, totalPages, title, and date are auto-filled (see example below). Takes precedence over footerText.
pageRange	string	—	Only convert the selected pages, e.g. "1-3,5" or "1,2,3". Omitted or empty converts every page.
conversionDelay	number	0	Delay in seconds after the page loads before rendering the PDF. Useful for slow-loading or animated content. Range: 0 .. 30
waitForElement	string	—	Wait for this CSS selector to appear in the DOM before converting (e.g. "#chart-loaded").
waitForElementTimeout	number	30000	How long to wait for waitForElement (milliseconds) before failing. Range: 1000 .. 120000
javascriptEnabled	boolean	true	Allow web pages to run JavaScript before rendering.
userJs	string	—	JavaScript executed in the page before conversion begins, e.g. "document.body.style.background = '#fff'".
userCss	string	—	Additional CSS applied to the page before conversion.
hideElements	string	—	Comma-separated CSS selectors of elements to hide during conversion (e.g. ".cookie-banner, #ads").
showElements	string	—	Comma-separated CSS selectors of elements to keep visible; all other elements are hidden.
viewportWidth	number	1366	Browser viewport width in pixels. Range: 200 .. 4000
viewportHeight	number	1024	Browser viewport height in pixels. Range: 200 .. 4000
cssMediaType	string	screen	Emulate a CSS media type, e.g. screen or print, before converting.
scale	number	1	Scale of the rendered content (0.1 to 2). 1 = 100%. Range: 0.1 .. 2
loadLazyContent	boolean	false	Scroll through the page to trigger lazy-loaded images and content before converting.
avoidBreakElements	string	—	Comma-separated CSS selectors that pages should not break across.
breakBeforeElements	string	—	Comma-separated CSS selectors that should start a new page before them.
breakAfterElements	string	—	Comma-separated CSS selectors that should start a new page after them.

Example request bodyjson

{
  "file": "input.html",
  "pageSize": "A4",
  "pageWidthMm": 0,
  "pageHeightMm": 0,
  "landscape": false,
  "printBackground": true,
  "marginTop": "20px",
  "marginRight": "20px",
  "marginBottom": "20px",
  "marginLeft": "20px",
  "headerText": "",
  "footerText": "",
  "headerHtml": "",
  "footerHtml": "",
  "pageRange": "",
  "conversionDelay": 0,
  "waitForElement": "",
  "waitForElementTimeout": 30000,
  "javascriptEnabled": true,
  "userJs": "",
  "userCss": "",
  "hideElements": "",
  "showElements": "",
  "viewportWidth": 1366,
  "viewportHeight": 1024,
  "cssMediaType": "screen",
  "scale": 1,
  "loadLazyContent": false,
  "avoidBreakElements": "",
  "breakBeforeElements": "",
  "breakAfterElements": ""
}

Examples

Drop-in snippets for the options above.

HTML footer with page numbershtml

<span class='left'>Confidential</span>
<span class='right'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></span>

HTML header with title and datehtml

<span class='left'><span class='title'></span></span>
<span class='right'><span class='date'></span></span>

Styled header with inline CSShtml

<style>
  .left { float: left; font-size: 9px; color: #666; }
  .right { float: right; font-size: 9px; color: #666; }
</style>
<span class='left'>Quarterly Report</span>
<span class='right'>Page <span class='pageNumber'></span></span>

Convert only specific pagesbash

curl -X POST https://api.fileswitch.co/api/v1/converter/html-to-pdf \
  -H "Authorization: Bearer fc_YOUR_API_KEY" \
  -F "file=@report.html" \
  -F "pageRange=1-3,5"

Response

Every conversion endpoint returns the same success / message / data envelope. The data object is a Conversion record with a temporary downloadUrl.

Response bodyjson

{
  "success": true,
  "message": "Conversion completed",
  "data": {
    "id": "b10a5f2e-8c1e-4b3a-9c1d-2e3f4a5b6c7d",
    "inputFormat": "html",
    "outputFormat": "pdf",
    "inputFileName": "document.html",
    "outputFileName": "document.pdf",
    "inputFileSize": 45210,
    "outputFileSize": 88431,
    "status": "completed",
    "error": null,
    "creditCost": 2,
    "downloadUrl": "/api/v1/converter/download/conversions%2Fb10a5f2e-8c1e-4b3a-9c1d-2e3f4a5b6c7d%2Foutput.pdf",
    "createdAt": "2026-07-31T13:00:00.000Z",
    "completedAt": "2026-07-31T13:00:02.000Z"
  }
}

Prepend https://api.fileswitch.co/api/v1 to the downloadUrl and download with the same credentials. Files are retained temporarily and auto-deleted. See the full field reference in Response Schema.

Related conversions

HTML to Markdown

html, htm md

Markdown to HTML

md, markdown html

Ready to convert html, htm → pdf? Start free — no credit card required.

Convert online Read getting started