§ ONLINE API · v1 LEGACY REFERENCE · MAINTAINED FOR EXISTING CUSTOMERS

HTML to PDF API v1. Legacy reference.

The v1 SelectPdf HTML to PDF REST API at https://selectpdf.com/api/ — GET-only, 18 query-string parameters, online since 2015. This page documents v1 as it stands, for customers whose integrations already target it. New integrations should use the v2 REST API — a strict superset of v1, with POST + JSON, four engines, async jobs, multipart upload and 90 parameters.

See the v2 REST API → Get a free trial key Jump to v1 parameters ↓
↔V1 VS V2

v1 is kept online. v2 is the recommended path.

Both APIs run on the same SelectPdf engine and produce the same PDFs. v1 is the original surface, kept available so existing customers don't have to migrate on a schedule. v2 is a strict superset — same parameter names where they overlap, plus everything that came after.

V1 · KEPT ONLINE

Maintained for existing customers

Endpoint at /api/, GET-only, 18 parameters, four return codes. Same engine, same output quality as v2. Existing keys keep working — no migration required.

V2 · SUPERSET

POST, JSON, async, multipart

v2 keeps GET but adds POST with application/json or application/x-www-form-urlencoded, asynchronous jobs via async=True, and multipart HTML file uploads.

V2 · 90 PARAMETERS

Every v1 parameter, plus 74 more

All 18 v1 parameter names work unchanged in v2. v2 adds custom headers/footers, bookmarks from CSS selectors, viewer hints, engine selection (WebKit/Blink/Chromium), and more. Full v2 reference →

§QUICKSTART

One endpoint. GET only. All parameters in the query string.

v1 has no SDK / no client libraries — the contract is plain HTTP. Append the parameters to the URL and request it from any HTTP client. The response body is the generated PDF (when the conversion succeeds) or a plain-text error (when it fails).

GET — copy / paste into your browser or curl
GET https://selectpdf.com/api/?key=YOUR_KEY&url=https://example.com
v1-convert.sh 
curl "https://selectpdf.com/api/?key=$SELECTPDF_KEY&url=https://en.wikipedia.org/wiki/PDF&page_size=A4&page_orientation=Portrait" \
  --output wikipedia-pdf.pdf
  1. End point: https://selectpdf.com/api/ — note the single /api/; v2 uses /api2/convert/.
  2. Method: GET only. All parameters travel in the query string — no request body, no JSON, no form-encoded POST.
  3. Input source: exactly one of url (public web page) or html (raw HTML string, paired with optional base_url).
  4. Encoding: URL-encode url, html and base_url before appending them. Reserved characters (&, =, spaces, quotes) must be encoded or the API parses your request wrong.
§PARAMETERS

18 query-string parameters, in one place.

Append any combination to the v1 endpoint URL. key is always required; exactly one of url or html must be supplied. The remaining parameters are optional and default to the values shown.

18 / 18
§ REQUIRED 4 PARAMETERS

Endpoint, key and input source

Every v1 request needs the license key plus one input source — pass url for a public web page, or html (and optionally base_url) for a raw HTML string.

PARAMETER
DESCRIPTION
key
string
Your SelectPdf license key. Pass it as a query-string parameter on every request. The same key works on both v1 (/api/) and v2 (/api2/convert/).
url
string (url-encoded)
URL of the web page to convert. Must be a fully-qualified absolute URL. URL-encode the value before appending it to the query string. Exactly one of url or html must be set.
html
string (url-encoded)
Raw HTML source to convert, in place of a URL. URL-encode the value before appending it to the query string. Pair with base_url so relative asset paths resolve correctly.
base_url
string (url-encoded)
Optional base URL used to resolve relative <img>, <link> and <script> paths inside the html parameter. Has no effect when url is used.
§ PAGE SETUP 2 PARAMETERS

Page size and orientation

Defaults are A4 / Portrait. v1 supports nine page-size presets — for any other format, use v2 (which adds custom-dimension parameters).

PARAMETER
DESCRIPTION
page_size
enum default: A4
Page size of the generated PDF.
A1 A2 A3 A4 A5 Letter HalfLetter Ledger Legal
page_orientation
enum default: Portrait
Page orientation of the generated PDF.
Portrait Landscape
§ MARGINS 4 PARAMETERS

All four page margins

Measured in points (1pt = 1/72in). Default 5pt on every side. Set to 0 for an edge-to-edge PDF, or larger for printer-safe gutters.

PARAMETER
DESCRIPTION
margin_top
int (pt) default: 5
Top margin of the generated PDF, in points.
margin_right
int (pt) default: 5
Right margin of the generated PDF, in points.
margin_bottom
int (pt) default: 5
Bottom margin of the generated PDF, in points.
margin_left
int (pt) default: 5
Left margin of the generated PDF, in points.
§ NUMBERING & SECURITY 3 PARAMETERS

Page numbers and PDF passwords

Optional. Either or both passwords can be set. The user password gates opening; the owner password gates printing, copying and editing inside a PDF reader.

PARAMETER
DESCRIPTION
page_numbers
bool default: True
When True, the current page number is rendered in the footer of every PDF page.
True False
user_password
string
Password required to open the generated PDF document.
owner_password
string
Password required to view or modify (print, copy, edit) the generated PDF.
§ RENDERING 5 PARAMETERS

CSS media type, viewport and load timing

Tune how the page is rendered before it is captured. Larger min_load_time helps pages with deferred JavaScript or lazy-loaded images.

PARAMETER
DESCRIPTION
use_css_print
bool default: False
Use the CSS Print media type instead of Screen. Enable when the page declares @@media print styles.
True False
web_page_width
int (px) default: 1024
Width used by the converter's internal browser window, in pixels.
web_page_height
int (px) default: 0
Height used by the converter's internal browser window, in pixels. 0 means the height is auto-calculated to fit the rendered page.
min_load_time
int (sec) default: 1
Minimum seconds to wait before snapshotting the rendered page — helps pages with deferred JavaScript or lazy-loaded images.
max_load_time
int (sec) default: 30
Maximum seconds the converter will wait for the page to load. Up to 120 seconds allowed. Exceeding the limit returns a timeout error.
§RETURN CODES

Four HTTP status codes v1 ever returns.

v1 keeps the surface small. v2 adds 202 Accepted (async submission), 429 Too Many Requests (concurrency cap with Retry-After) and 503 Service Unavailable (demo endpoint overload) — useful when you need richer client-side error handling.

200 OK
The conversion succeeded. The response body is the generated PDF, served with Content-Type: application/pdf.
400 BAD REQUEST
Neither url nor html was supplied (or both were). The plain-text response body explains which is missing.
401 AUTHORIZATION REQUIRED
The key parameter is missing, malformed, expired, or out of credits. The plain-text response body explains which case applies.
499 CUSTOM
The conversion itself failed — the target page errored, timed out (max_load_time elapsed) or the engine refused to render it. The plain-text response body carries the specific error.
⇪MIGRATE TO V2

From v1 to v2 in one line of code.

The v1 → v2 migration is the smallest possible change: swap the endpoint path and keep everything else. Every v1 parameter name and semantic is preserved in v2, so existing query strings work unmodified.

Endpoint: replace https://selectpdf.com/api/ with https://selectpdf.com/api2/convert/. That's the whole required change — your existing key, URL/html, page-size, margins, security and rendering parameters all keep working.

What you unlock by switching: POST + JSON request bodies, four rendering engines (WebKit, WebKit Restricted, Blink, Chromium) via the engine parameter, custom headers and footers, automatic PDF bookmarks from CSS selectors, viewer-mode hints, asynchronous conversion via async=True, and 90 parameters in total instead of 18. Browse the full v2 reference →

Official client libraries for v2 are published on GitHub under MIT for .NET, Java, PHP, Python, Node.js, Ruby and Perl — none of these existed for v1. See all seven on the v2 overview →

?FAQ

v1, answered.

Six quick answers for customers running on v1, plus the migration path to the v2 REST API.

Yes. The v1 endpoint at https://selectpdf.com/api/ is maintained for existing customers — the same engine, the same output. New integrations should use the v2 REST API at /api2/convert/, which is a strict superset of v1.
Yes. Keys are issued by the same SelectPdf account system; a single key works on both the v1 endpoint (/api/) and the v2 endpoint (/api2/convert/). No migration is needed for the keys themselves — only for the request shape if you switch endpoints.
v2 is a strict superset: 90 parameters versus 18, POST + JSON body in addition to GET, asynchronous jobs, multipart file upload, four selectable rendering engines (WebKit, WebKit Restricted, Blink, Chromium), per-tier concurrent-request budgets, and official client libraries in seven languages (.NET, Java, PHP, Python, Node.js, Ruby, Perl) — all open source under MIT.
No. Every v1 parameter — key, url, html, base_url, page_size, page_orientation, the four margins, page_numbers, user_password, owner_password, use_css_print, web_page_width, web_page_height, min_load_time, max_load_time — works in v2 with the same name and the same semantics. Migrating is a one-line endpoint swap from /api/ to /api2/convert/; the rest of your query string is unchanged.
Same place as v2 — the API-key signup form. One key works on both endpoints, so there is no separate v1 signup. A 7-day free trial with 200 conversions is available without a credit card.
Both. Pass url=… for a public web page, or html=… for a raw HTML string. If your HTML uses relative paths to images, stylesheets or scripts, add base_url=… so those resolve correctly during rendering. All three parameters must be URL-encoded.