PDFCrowd API v2 Migration Guide

To migrate from PDFCrowd API v1 to v2, update the client or HTTP request, map conversion methods and settings, and compare generated files using representative inputs. The change is mostly syntactic, but it is not fully backward compatible: defaults, units, booleans, page settings, watermark inputs, and output behavior can change. PDFCrowd describes v2 as its current major API and v1 as frozen; availability of v1 may depend on your account. Confirm current access and language-specific method signatures in the PDFCrowd API documentation. [Migration guide] [Versioning]

1. Plan the migration

PDFCrowd’s client-library migration sequence is:

1. Instantiate the API v2 client.
2. Migrate each conversion method.
3. Migrate settings and check their semantics.
4. Update error handling.

The vendor says its client libraries support both API versions, so both implementations can run side by side under the same account. Use that option to compare outputs before switching callers. Treat this as a migration of both request behavior and rendering configuration, not just a class or endpoint rename. [PDFCrowd migration guide]

Inventory before editing

• Record each v1 method, input type, output handling, and enabled option.
• Save representative source URLs, HTML files, and HTML strings.
• Note output format, page dimensions, margins, headers and footers, scaling, page limits, and watermark/background inputs.
• Record current authentication and request encoding.
• Record the converter version separately from the API major version.

2. Update client-library methods

The migration guide maps methods by both input and result handling. The exact signatures and return types vary by language library; consult the current language-specific API reference before adapting these mapping names.

API v1	API v2 file result	API v2 other result forms
convertURI	convertUrlToFile	convertUrl or convertUrlToStream
convertFile	convertFileToFile	convertFile or convertFileToStream
convertHtml	convertStringToFile	convertString or convertStringToStream

V2 examples use an HtmlToPdfClient class where older examples may use Client or Pdfcrowd. Do not infer constructor arguments or exception names from another language’s example. Port the method intent, then verify it against the installed library’s API reference. [Migration guide]

3. Migrate HTTP integrations

For direct HTTP integrations, PDFCrowd’s migration guide documents the v2 conversion endpoint as https://api.pdfcrowd.com/convert/, HTTP Basic authentication using the account username and API key, and multipart inputs named url, file, or text. This replaces the v1 src-style input pattern and v1 username/key fields. Keep credentials out of source control and logs. [Migration guide]

Runnable cURL examples

# Convert a public URL to PDF
curl --fail-with-body -u "YOUR_USERNAME:YOUR_API_KEY" \
  -F "url=https://example.com/" \
  "https://api.pdfcrowd.com/convert/" \
  -o output.pdf

# Convert an HTML file
curl --fail-with-body -u "YOUR_USERNAME:YOUR_API_KEY" \
  -F "file=@./page.html" \
  "https://api.pdfcrowd.com/convert/" \
  -o output.pdf

# Convert an HTML string
curl --fail-with-body -u "YOUR_USERNAME:YOUR_API_KEY" \
  -F "text=<html><body><h1>Hello</h1></body></html>" \
  "https://api.pdfcrowd.com/convert/" \
  -o output.pdf

The cURL examples show the v2 endpoint, Basic authentication, and input field names from the migration guide. Confirm any additional option names and multipart encoding requirements against the current reference. --fail-with-body requires a sufficiently recent cURL; remove it on older installations and check the HTTP status explicitly. [Migration guide]

Python HTTP example

import os
import requests

ENDPOINT = "https://api.pdfcrowd.com/convert/"
AUTH = (os.environ["PDFCROWD_USERNAME"], os.environ["PDFCROWD_API_KEY"])

# URL input. For HTML text, use data={"text": html_string};
# for a file, use files={"file": open("page.html", "rb")}.
response = requests.post(
    ENDPOINT,
    auth=AUTH,
    data={"url": "https://example.com/"},
    timeout=(10, 180),
)
response.raise_for_status()
with open("output.pdf", "wb") as output:
    output.write(response.content)

Set the two environment variables before running this example. For file input, close the file after the request, preferably with a with open(...) block around requests.post. The timeout values are example client-side limits, not PDFCrowd service guarantees.

Node.js HTTP example

const endpoint = 'https://api.pdfcrowd.com/convert/';
const username = process.env.PDFCROWD_USERNAME;
const apiKey = process.env.PDFCROWD_API_KEY;
if (!username || !apiKey) throw new Error('Set PDFCROWD_USERNAME and PDFCROWD_API_KEY');

const auth = Buffer.from(`${username}:${apiKey}`).toString('base64');
const form = new FormData();
form.set('url', 'https://example.com/');

const response = await fetch(endpoint, {
  method: 'POST',
  headers: { Authorization: `Basic ${auth}` },
  body: form,
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
  throw new Error(`PDFCrowd returned HTTP ${response.status}: ${await response.text()}`);
}
const pdf = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) => writeFile('output.pdf', pdf));

This uses the built-in fetch, FormData, and AbortSignal.timeout APIs available in modern Node.js releases. If your runtime lacks them, use its supported HTTP and multipart packages and preserve the same endpoint, Basic authentication, and field names.

4. Check settings that change behavior

Review every option actually used by your integration against PDFCrowd’s full migration table. These documented changes are common sources of output drift. [Migration guide]

Area	Migration concern	What to do
Images, backgrounds, JavaScript	V1 positive switches such as enableImages, enableBackgrounds, and enableJavaScript map to negative v2 settings such as setDisableImageLoading, setNoBackground, and setDisableJavascript.	Invert the boolean. Check HTTP no_images, no_backgrounds, and no_javascript equivalents too.
Text encoding	V1 defaults to UTF-8; v2 attempts auto-detection.	Set encoding explicitly where character output must remain stable.
Page layout and zoom	Enum strings differ. CONTINUOUS and CONTINUOUS_FACING are unsupported; the guide maps the old continuous layout to single-page.	Map values deliberately and check unsupported modes rather than passing old strings through.
Scale factor	setPdfScalingFactor / pdf_scaling_factor maps to a v2 scale factor whose value is multiplied by 100.	Convert the existing value according to the guide and compare page size and content scale.
Watermarks and backgrounds	V1 may accept raster images; v2 multipage watermark/background settings use a PDF file.	Prepare an appropriate PDF input and validate page alignment and transparency.
SSL setting	Old useSSL maps to setUseHttp with an inverted argument.	Invert the setting rather than copying its boolean.
Dimensions	V1 treats bare numeric dimensions as points; v2 requires a unit suffix.	Specify mm, in, cm, or pt on dimensions.
Headers and footers	V2 uses HTML classes pdfcrowd-source-url, pdfcrowd-page-number, and pdfcrowd-page-count instead of %u, %p, and %n. Their placement changes from the margin area to the printing area.	Update markup and configure header/footer heights to prevent overlap or clipping.
Page limit	V1 max_pages maps to v2 print page range.	For the first N pages, the guide gives -N; use the v2 range syntax for other selections.

Some settings have no counterpart in one direction. Compare your actual option set with the full mapping table instead of assuming every v1 setting is available or unchanged in v2.

5. Separate API version from converter version

“API v2” and the converter version are different choices. PDFCrowd’s versioning page lists converter 24.04 as updated and 20.10 and 18.10 as frozen within API v2. The vendor recommends selecting one converter version and using it consistently for predictable output; changing converter versions may alter appearance or behavior. Confirm the currently offered options in the versioning documentation before pinning a value. [PDFCrowd API Versioning]

PDFCrowd describes v2 as supporting current HTML5, CSS3, and JavaScript specifications and lists capabilities including custom post-load JavaScript, cookies, delayed printing, partial-page conversion, conversion logs, and conversions among HTML, PDF, and image formats. These are vendor-described capabilities, not a guarantee that every document renders identically or faster. [What’s new in API v2?]

6. Validate outputs before cutover

Run old and new implementations side by side where practical. This is a migration recommendation based on the documented incompatibilities and converter-version warning, not a claim that any particular comparison has been performed.

1. Choose representative inputs: JavaScript-rendered content, remote fonts, non-Latin scripts, images, tables, headers/footers, and custom page settings as applicable.
2. Hold source content, conversion options, and converter version constant during each comparison.
3. Compare page count, dimensions, text encoding, line breaks, image presence, margins, headers/footers, and watermark placement.
4. Check both successful files and errors, including inaccessible source URLs and missing remote resources.
5. Repeat with the intended production converter version and explicit settings for behavior-sensitive defaults.
6. Switch traffic only after differences are understood and the error handling is updated.

7. Troubleshooting

Symptom	Likely cause	Fix
Authentication fails	V1 credential fields or an incorrect Basic auth pair are still being sent.	Use HTTP Basic authentication with the PDFCrowd username and API key; ensure neither value has whitespace or is logged.
Input is missing or rejected	The request still sends v1 src or targets a v1 endpoint.	Use the v2 conversion endpoint and the appropriate multipart field: url, file, or text.
Images, backgrounds, or scripts disappear	A positive v1 boolean was copied into a negative v2 option without inversion.	Invert the value and inspect the request or client settings actually sent.
Characters differ	V2 auto-detection selected a different encoding than v1’s UTF-8 default.	Set the expected text encoding explicitly and rerun the affected documents.
Page size or scale changed	Bare dimensions now need units, or scale factor values need conversion.	Add an explicit unit suffix and apply the documented factor mapping; compare output geometry.
Header/footer is clipped or overlaps content	V2 places header/footer content in the printing area and uses CSS classes for variables.	Replace placeholder variables with the v2 classes and configure header/footer heights.
Continuous layout no longer works	The old layout value is unsupported in v2.	Choose a supported v2 layout such as the documented single-page mapping where appropriate.
Watermark no longer accepts the old asset	The v2 multipage watermark/background input expects a PDF file.	Supply a PDF and verify alignment across pages.
Same input renders differently over time	The converter version differs or was not pinned consistently.	Select a converter version and keep it consistent; investigate changes when deliberately upgrading.
Client code fails after a method rename	The method return mode or signature differs in the installed language library.	Check the current language-specific reference and choose file, variable, or stream handling intentionally.

8. Performance, reliability, and cost considerations

The supplied PDFCrowd references do not provide a numerical performance benchmark or cost figures, so do not assume a migration will be faster or cheaper. Conversion duration and output depend on source complexity, resource loading, chosen settings, and converter version; measure with your own representative workload. For reliability, use finite client timeouts, handle non-success responses and conversion errors, avoid blind retries for deterministic invalid input, and make retries bounded for transient network failures. Check current account pricing and limits directly with PDFCrowd before planning capacity.

To reduce output surprises, keep the converter version consistent, set encoding and geometry explicitly where needed, and record conversion errors during rollout. PDFCrowd says v2 provides detailed conversion logs; consult its current documentation for how to enable and retrieve them. [PDFCrowd API v2 FAQ]

9. An alternative for website screenshots

If your task is capturing a web page as an image rather than converting a document to PDF, ScreenshotNeo is the alternative to try first: it removes cookie banners, popups, and chat widgets before capture, and only clean shots are billed. It is a website screenshot API and MCP server by Yorker Media, so it complements a PDF conversion workflow rather than replacing PDFCrowd’s document conversion API.

Or skip the browser setup

One GET request returns a PNG, JPEG, WebP, or PDF. The example below saves a website screenshot as WebP; see the ScreenshotNeo API documentation for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

FAQ

Can v1 and v2 run during the same migration?

PDFCrowd says its client libraries support both versions and can run side by side under the same account. Confirm v1 availability for your account, since the vendor describes it as a legacy option for eligible older accounts. [Legacy API FAQ]

Does API v2 guarantee the same PDF output?

No. The migration guide lists behavior changes and the converter version can affect appearance. Compare representative outputs and pin relevant settings and converter version.

Is changing converter version part of moving to API v2?

No. API major version and converter version are separate. You can migrate the API while selecting a converter version, but keep the distinction explicit in configuration. [PDFCrowd API Versioning]

Does v2 support converting only part of a page?

PDFCrowd lists partial-page printing among v2 capabilities. Check the current API reference for the option and its language-specific syntax. [What’s new in API v2?]

Research note: Historical migration details and method mappings above are based on PDFCrowd’s documentation. Check current language-specific references because signatures and availability can change.