REST API documentation

Conv2pdf REST API — convert, merge, split, compress, protect and number PDFs from your application — 20 tools exposed via 6 REST endpoints. Hosting in France, GDPR-compliant, no US third party in the processing chain.

Get started

Quick start

  1. Create an account (free, email — no password required)
  2. From your dashboard, create an API key (free Dev plan, 300 conversions included to test, valid 12 months, no renewal)
  3. Convert a file in two calls: the upload, which answers once the conversion is done with a download_url, then the download.
curl -X POST https://api.conv2pdf.com/v1/convert/office-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@report.docx"
# {"job_id": "abc123…", "status": "success", "download_url": "/v1/download/abc123…", …}

curl https://api.conv2pdf.com/v1/download/abc123… \
  -H "Authorization: Bearer cpdf_live_..." \
  -o report.pdf

download_url is a path relative to the host: prefix it with https://api.conv2pdf.com, not with the base URL, which already ends in /v1. The result stays available for one hour.

Node.js
import { readFile, writeFile } from 'node:fs/promises';

const API = 'https://api.conv2pdf.com';
const headers = { Authorization: 'Bearer cpdf_live_...' };

const form = new FormData();
form.append('file', new Blob([await readFile('./report.docx')]), 'report.docx');

const res = await fetch(`${API}/v1/convert/office-to-pdf`, { method: 'POST', headers, body: form });
const job = await res.json();
if (!res.ok) throw new Error(job.error);

const pdf = await fetch(API + job.download_url, { headers });
await writeFile('./report.pdf', Buffer.from(await pdf.arrayBuffer()));
Python
import requests

API = 'https://api.conv2pdf.com'
headers = {'Authorization': 'Bearer cpdf_live_...'}

with open('report.docx', 'rb') as f:
    r = requests.post(f'{API}/v1/convert/office-to-pdf', headers=headers, files={'file': f})
job = r.json()
if not r.ok:
    raise RuntimeError(job['error'])

pdf = requests.get(API + job['download_url'], headers=headers)
with open('report.pdf', 'wb') as out:
    out.write(pdf.content)
PHP

With the official SDK (recommended): composer require conv2pdf/php, see the repo and its examples.

use Conv2pdf\Conv2pdf;

$c = new Conv2pdf('cpdf_live_...');
$job = $c->convert('office-to-pdf', 'report.docx');
$c->download($job['download_url'], 'report.pdf');

Without a dependency:

$api = 'https://api.conv2pdf.com';
$auth = ['Authorization: Bearer cpdf_live_...'];

$ch = curl_init("$api/v1/convert/office-to-pdf");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => $auth,
  CURLOPT_POSTFIELDS => ['file' => new CURLFile('report.docx')],
]);
$job = json_decode(curl_exec($ch), true);

$ch = curl_init($api . $job['download_url']);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $auth]);
file_put_contents('report.pdf', curl_exec($ch));

Authentication and base URL

https://api.conv2pdf.com/v1

Every request carries the HTTP header Authorization: Bearer <your_key>. A missing, revoked or non-existent key returns 401. Keys are created from the dashboard; all the keys of an account share its quota.

Concepts

Job lifecycle

  1. Conversion: POST /v1/convert/:tool answers when the conversion is done, with a job_id and a download_url.
  2. Download: GET /v1/download/:jobId, for one hour. After that the input and the output are deleted, and the download returns 410 file_expired.
  3. Deletion, optional: DELETE /v1/job/:jobId erases the job and its file without waiting for the hour.

GET /v1/job/:jobId reads the status of a job at any time. A job is only reachable with the key that created it; any other key gets 403 forbidden.

Limits

LimitValueBeyond
File size10 MB on the Dev plan, 200 MB on paid plans413 file_too_large
Files per conversion1 on the Dev plan (2 for merge-pdf), 20 on paid plans402 plan_limit_files
Request size220 MB, files and fields combined413 payload_too_large
Multipart elements20 files, 10 fields, 32 parts in total413 too_many_parts
Conversion rate20 per minute per key429 rate_limited
Rate on other endpoints300 requests per minute per IP429 rate_limited
File retention1 hour after the conversion410 file_expired
Pages, duration, output sizespecific to each tool, see its entry422 too_many_pages, 504 conversion_timeout…

Quotas and billing

Each account has a quota according to its plan (see API pricing), shared by all its keys.

  • Paid plans: the quota is monthly and resets on an anniversary date (not on the 1st of the month). The timestamp of the next reset is returned in quota_period_end; the used counter goes back to zero then.
  • Dev plan: the 300 conversions included at signup are valid for 12 months from when they were granted (credits_expire_at) and do not renew (quota_period_end is null, and so is period_end: a trial is not billed).
  • Overage: a small overage is tolerated (soft_cap_limit, +10%) before the 429 quota_exceeded block.
  • Alerts: an email warns you at 80% of your quota and when it runs out, on every plan, and 30 days before your trial credits expire.

You can read the quota state at any time, at no cost, with GET /v1/quota. Every conversion authenticated with an API key returns the same quota object.

Counted

  • a conversion that succeeds;
  • a file refused after it has been read: unreadable, scanned, too many pages, already protected.

Free

  • a file refused on arrival: type, size, missing password;
  • a refused parameter: page range, rotation, quality, password too short…;
  • a rate refusal (429 rate_limited);
  • a failure on our side (500 conversion_failed, 504 conversion_timeout).

Errors and retries

Every error response carries an error field: a stable code you can branch on. The extra fields tell you what to fix. Refusals at the door (upload, plan, content) also carry plan; errors raised during conversion carry job_id and status (rejected for a verdict on the file, failed for a breakdown).

  • Retry after the given delay: 429 rate_limited (retry_after field in seconds, Retry-After header) and 503 server_busy (within 5 s, Retry-After header).
  • Do not retry before the reset: 429 quota_exceeded, until quota_period_end; on the Dev plan, as after 402 credits_expired, only a paid plan (upgrade) reopens access.
  • Never retry: 410 file_expired and 410 job_deleted, the resource is gone.
  • Fix the request or the file: the other 4xx. A refused parameter costs nothing.
  • Breakdowns: 500 conversion_failed and 504 conversion_timeout are refunded to the quota.

Every code, with the fields it carries, is described in Error codes.

Reference

Endpoints

EndpointPurpose
POST /v1/convert/:toolConvert one or more files
GET /v1/download/:jobIdDownload the result
GET /v1/job/:jobIdRead the status of a job
DELETE /v1/job/:jobIdDelete a job and its file
GET /v1/quotaRead the quota of the key, at no cost
GET /v1/toolsList the tools, their formats and bounds

POST /v1/convert/:tool

Performs a conversion and answers when it is done. Files and parameters are sent as multipart/form-data: the file in the file field, repeated to send several. The values of :tool and the fields of each tool are described in Tools.

Successful response. The quota object is only present for calls authenticated with an API key.

{
  "job_id": "abc123…",
  "status": "success",
  "download_url": "/v1/download/abc123…",
  "size_bytes": 124533,
  "quota": {
    "plan": "starter",
    "quota": 1000,
    "used": 42,
    "soft_cap_limit": 1100,
    "status": "ok",
    "period_end": 1715789012345,
    "quota_period_end": 1715789012345,
    "credits_expire_at": null
  }
}

GET /v1/download/:jobId

Downloads the converted file, for one hour. It is served with Cache-Control: no-store and the MIME type of the result: application/pdf, image/jpeg for heic-to-jpg, DOCX for pdf-to-word, application/zip for pdf-to-image and split-pdf.

curl https://api.conv2pdf.com/v1/download/abc123… \
  -H "Authorization: Bearer cpdf_live_..." \
  -o output.pdf

GET /v1/job/:jobId

Returns a job’s status and metadata (status, size, dates). Handy to check that a conversion is ready before downloading it.

curl https://api.conv2pdf.com/v1/job/abc123… \
  -H "Authorization: Bearer cpdf_live_..."

DELETE /v1/job/:jobId

Immediately deletes a job and its file, without waiting for the automatic expiry (1 hour). The job then answers 410 job_deleted.

curl -X DELETE https://api.conv2pdf.com/v1/job/abc123… \
  -H "Authorization: Bearer cpdf_live_..."

GET /v1/quota

Returns the quota state of the key: plan, usage, caps and dates, that is the quota object of a conversion response, on its own. The call is free and has no side effect, so it is the one to use to check a key, for example in the credential test of a connector. It also answers when the quota is at its cap (status is hard_cap) or the Dev trial has expired (credits_expire_at is in the past), where conversions answer 429 or 402.

curl https://api.conv2pdf.com/v1/quota \
  -H "Authorization: Bearer cpdf_live_..."

GET /v1/tools

Returns the list of available tools, their limits and accepted formats.

curl https://api.conv2pdf.com/v1/tools \
  -H "Authorization: Bearer cpdf_live_..."

Tools

20 tools available. The up-to-date machine list (accepted formats, file bounds) is returned by GET /v1/tools. The type of a file is read from its content, not from its extension (see 415 unsupported_content).

Parameters are multipart/form-data fields sent with the file. On pdf-to-word, pdf-to-image, compress-pdf, split-pdf, extract-pages, rotate-pdf, watermark-pdf and page-numbers-pdf, the password field opens a PDF that asks for a password; the result has no password. A PDF that only restricts printing or copying needs none.

Tool (:tool)InputFilesOutput
Conversions
image-to-pdfPNG, JPG, WEBP, GIF, TIFF1PDF
heic-to-jpgHEIC, HEIF1JPG
heic-to-pdfHEIC, HEIF1PDF
office-to-pdfDOC(X/M), ODT, RTF, TXT, XLS(X/M), ODS, CSV, PPT(X/M), ODP, ODG, SXW/SXC/SXI/SXD, FODT/FODS/FODP/FODG, PAGES1PDF
epub-to-pdfEPUB1PDF
xps-to-pdfXPS, OXPS1PDF
ps-to-pdfPS, EPS1PDF
html-to-pdfHTML, HTM, XHTML1PDF
url-to-pdfhttp/https address (url field)0PDF
pdf-to-wordPDF1DOCX
pdf-to-imagePDF1ZIP (1 image/page)
PDF operations
merge-pdfPDF2 to 20PDF
split-pdfPDF1ZIP (1 PDF/page)
extract-pagesPDF1PDF
compress-pdfPDF1PDF
rotate-pdfPDF1PDF
protect-pdfPDF1PDF
unlock-pdfPDF1PDF
watermark-pdfPDF1PDF
page-numbers-pdfPDF1PDF

Conversions

image-to-pdf

PNG, JPG, WEBP, GIF, TIFF → PDF · 1 file · no fields

Specific errors: 415 unsupported_format, an image in a format the tool cannot read.

curl -X POST https://api.conv2pdf.com/v1/convert/image-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@photo.jpg"
heic-to-jpg

HEIC, HEIF → JPG · 1 file · no fields

curl -X POST https://api.conv2pdf.com/v1/convert/heic-to-jpg \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@IMG_0001.heic"
heic-to-pdf

HEIC, HEIF → PDF · 1 file · no fields

curl -X POST https://api.conv2pdf.com/v1/convert/heic-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@IMG_0001.heic"
office-to-pdf

DOC(X/M), ODT, RTF, TXT, XLS(X/M), ODS, CSV, PPT(X/M), ODP, ODG, SXW/SXC/SXI/SXD, FODT/FODS/FODP/FODG, PAGES → PDF · 1 file · no fields

Also converts Apple Pages documents, recognized by their .pages extension; Numbers and Keynote files are refused.

Specific errors: 415 unsupported_content with detected_type iwork_numbers or iwork_keynote for a Numbers or Keynote file; 422 password_protected for a locked iWork document.

curl -X POST https://api.conv2pdf.com/v1/convert/office-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@report.docx"
epub-to-pdf

EPUB → PDF · 1 file · no fields

Lays the book out on A4 pages, with its table of contents and internal links; the fonts of the book are replaced by standard fonts.

Specific errors: 422 epub_blank_output, pages that would come out blank (a fixed layout of full-page images, such as comics or picture books); 422 epub_too_long, a book beyond 1,500 pages (the body carries pages and max_pages); 422 password_protected, a DRM-protected book.

curl -X POST https://api.conv2pdf.com/v1/convert/epub-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@book.epub"
xps-to-pdf

XPS, OXPS → PDF · 1 file · no field

XPS and OpenXPS documents, recognised from their content: every page keeps its size, its fonts and its vector drawings; links and the document outline are kept.

Specific errors: 422 source_unreadable, a package the engine cannot open; 422 too_many_pages beyond 1,500 pages (the body carries pages and max_pages).

curl -X POST https://api.conv2pdf.com/v1/convert/xps-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@order.xps"
ps-to-pdf

PS, EPS → PDF · 1 file · no fields

PostScript and EPS files, recognized from their content: text stays text, drawings stay vector, an EPS gives one page at the size of the drawing, and a document that declares no page size is set on A4.

Specific errors: 422 source_unreadable, a PostScript program that fails; 422 ps_blank_output, a file that draws no page, such as a font or a library of procedures saved as PostScript; 422 too_many_pages beyond 500 pages; 504 conversion_timeout beyond 30 seconds.

curl -X POST https://api.conv2pdf.com/v1/convert/ps-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@drawing.eps"
html-to-pdf

HTML, HTM, XHTML → PDF · 1 file · no fields

Renders the printable version of the page, the one Ctrl+P would give: the text stays selectable, links stay clickable, and headings become bookmarks. Page size and margins come from the document’s @page; A4 with a 1 cm margin otherwise. The page’s JavaScript runs, with a short settling delay. The page has access to no local file and to no private network, and the content of a cross-origin iframe is not printed (empty area, no error).

Specific errors: 422 html_blank_output, an output where nothing is drawn (an empty file, a body hidden by the stylesheet), refused rather than delivered as a blank page; 422 too_many_pages beyond 500 pages; 504 conversion_timeout beyond 60 seconds.

curl -X POST https://api.conv2pdf.com/v1/convert/html-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@page.html"
url-to-pdf

http/https address → PDF · no file

The only tool that takes no file: it opens the address in the url field and renders it like html-to-pdf, in its printable version, with the same ceilings (500 pages, 60 seconds). The page is opened without a session: anything that requires a sign-in is out of reach.

Field: url, required: http or https address, 2,048 characters at most.

These are refused with 422 invalid_url, without being counted: an address carrying credentials, a private-network or loopback address, and a name that only refers to a local network. The reason is in cause: malformed, scheme, credentials, private_address (with address_kind), local_name or too_long.

Specific errors: 400 no_file_expected, a file was sent; 422 url_unreachable, the address did not respond; 422 url_http_error, the page replied with an error (its status in http_status); 422 url_blocked, the address points to a private network; 422 url_blank_page, a site that renders an empty page outside a browser.

curl -X POST https://api.conv2pdf.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "url=https://example.com/article"
pdf-to-word

PDF → DOCX · 1 file

Returns an editable .docx file. OCR is available to Premium accounts on the website only, and is not exposed through the API.

Field: password, optional: password that opens the PDF.

Specific errors: 422 pdf_scanned_needs_ocr, a scanned PDF with no text layer; 422 pdf_too_many_pages beyond 500 pages.

curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-word \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@report.pdf"
pdf-to-image

PDF → ZIP, one image per page · 1 file

Renders each page as an image at 150 DPI.

FieldRequiredValuesDefault
formatnopng, jpgpng
passwordnopassword that opens the PDF—

Specific errors: 422 too_many_pages beyond 100 pages; 422 output_too_large if the images exceed the maximum size (the body carries max_bytes and format).

curl -X POST https://api.conv2pdf.com/v1/convert/pdf-to-image \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@report.pdf" \
  -F "format=png"

PDF operations

merge-pdf

PDF → PDF · 2 to 20 files, 2 on the Dev plan · no other field

Merges the files in the order they are sent: repeat the file field. A password-protected PDF is unlocked first with unlock-pdf.

curl -X POST https://api.conv2pdf.com/v1/convert/merge-pdf \
  -H "Authorization: Bearer cpdf_live_..." \
  -F "file=@doc1.pdf" -F "file=@doc2.pdf" -F "file=@doc3.pdf"
split-pdf

PDF → ZIP, one PDF per page · 1 file

Returns each page in its own file (page-001.pdf, page-002.pdf…), gathered in a ZIP archive. The result carries the pages only: not the attachments, not the document metadata. To keep a selection of pages in a single PDF, use extract-pages.

Field: password, optional: password that opens the PDF.

Specific errors: 422 pdf_single_page, the PDF has a single page; 422 too_many_pages beyond 200 pages; 422 output_too_large if the archive would exceed 600 MB (the body carries max_bytes).

Compatibility: until October 2026, extraction was called split-pdf. A split-pdf call that carries a ranges field is still served as extract-pages: an existing integration has nothing to change. One difference: pages now come out in the order written (5,1,3 returns pages 5, 1 and 3) instead of sorted.

curl -X POST https://api.conv2pdf.com/v1/convert/split-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@report.pdf"
extract-pages

PDF → PDF · 1 file

Keeps the requested pages in a single PDF. Pages come out in the order written, each one once. The result carries those pages only: not the pages left out, not the attachments, not the document metadata.

FieldRequiredValuesDefault
rangesyese.g. 1-5,7,10-12; 11- runs to the last page, -4 starts from the first—
passwordnopassword that opens the PDF—

Specific errors: 400 field_required without ranges; 400 invalid_page_range, a selection the document does not allow, with the reason in cause (syntax, page_zero, beyond_last_page or whole_document), the refused part in range and, once the PDF has been opened, its page count in total_pages.

curl -X POST https://api.conv2pdf.com/v1/convert/extract-pages \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@report.pdf" \
  -F "ranges=1-5,7,10-12"
compress-pdf

PDF → PDF · 1 file

FieldRequiredValuesDefault
qualitynolow (72 DPI), medium (150 DPI), high (300 DPI)medium
passwordnopassword that opens the PDF—
curl -X POST https://api.conv2pdf.com/v1/convert/compress-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@big.pdf" \
  -F "quality=medium"
rotate-pdf

PDF → PDF · 1 file

FieldRequiredValuesDefault
rotationyes90, 180, 270, in degrees, clockwise—
passwordnopassword that opens the PDF—
curl -X POST https://api.conv2pdf.com/v1/convert/rotate-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@scan.pdf" \
  -F "rotation=90"
protect-pdf

PDF → PDF · 1 file

AES-256 encryption. The resulting PDF will prompt for the password on opening and apply the selected restrictions.

FieldRequiredValuesDefault
passwordyespassword to set, 6 to 64 characters—
prevent_printnoon prevents printingprinting allowed
prevent_copynoon prevents copying textcopying allowed

Specific errors: 400 password_too_short or password_too_long (the body carries min or max); 422 pdf_already_protected, an already encrypted PDF.

curl -X POST https://api.conv2pdf.com/v1/convert/protect-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@confidential.pdf" \
  -F "password=secret123" -F "prevent_print=on" -F "prevent_copy=on"
unlock-pdf

PDF → PDF · 1 file

Removes the password and the restrictions of a PDF.

Field: password, if the PDF asks for one: the PDF’s current password, to remove; leave it out for a PDF that opens without a password but restricts printing or copying.

Specific errors: 422 pdf_not_protected, an unprotected PDF.

curl -X POST https://api.conv2pdf.com/v1/convert/unlock-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@protected.pdf" \
  -F "password=secret123"
watermark-pdf

PDF → PDF · 1 file

FieldRequiredValuesDefault
textyeswatermark text, 50 characters at most—
passwordnopassword that opens the PDF—

Specific errors: 400 field_required without text; 422 unsupported_characters, the text contains characters the embedded fonts cannot render (the body carries field, quota is not consumed).

curl -X POST https://api.conv2pdf.com/v1/convert/watermark-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@contract.pdf" \
  -F "text=CONFIDENTIAL"
page-numbers-pdf

PDF → PDF · 1 file

FieldRequiredValuesDefault
positionnobottom-center, bottom-left, bottom-rightbottom-center
formatnofull ("X of N"), simple (the number only, no total)full
passwordnopassword that opens the PDF—
curl -X POST https://api.conv2pdf.com/v1/convert/page-numbers-pdf \
  -H "Authorization: Bearer cpdf_live_..." -F "file=@report.pdf" \
  -F "position=bottom-right"

Error codes

The shape of the body and what to retry are in Errors and retries. Errors shared by all tools, by HTTP code:

CodeErrorCause
400not_enough_files / too_many_filesFile count outside tool bounds. The body carries min and provided, or max.
400field_requiredRequired field missing or empty: ranges on extract-pages, text on watermark-pdf. The body carries field, plus example when the expected shape is not obvious. Quota is not consumed.
400invalid_rotation / invalid_page_range / invalid_quality / invalid_formatParameter outside the accepted values. The body carries what is accepted (allowed, valid) and, for a page selection, the reason in cause, the refused part in range and the page count of the document in total_pages. Quota is not consumed.
400bad_requestMultipart body refused by the parser: forbidden field name, invalid JSON field, or a body cut short in flight (code: "malformed_multipart"). The body carries code.
401missing_bearer_token / invalid_api_key / account_not_provisionedMissing auth, invalid or revoked key, or a key with no API account attached.
402plan_limit_filesMore files than the plan allows per conversion: 1 on the Dev plan, 20 on paid plans. The body carries plan and max_allowed — the limit actually applied, which is higher on a tool that requires several files (merge-pdf takes 2 even on Dev).
402credits_expiredDev plan trial credits past their validity date (12 months from when they were granted), whatever is left. The body carries expired_at and upgrade.
403forbiddenJob belongs to another key
404tool_not_found / job_not_foundTool or job does not exist
409job_not_readyThe job exists but has no output: conversion pending, failed or rejected. The body carries status (pending / failed / rejected).
410file_expired / job_deletedResource is gone for good: 1 h TTL exceeded, or job removed via DELETE /v1/job/:jobId. Do not retry.
413file_too_largeFile beyond the plan limit: 10 MB on the Dev plan, 200 MB on paid plans. When a higher plan would accept the file, the response carries upgrade with that plan, its monthly price excl. tax and its limit.
413payload_too_largeWhole request beyond 220 MB, files and fields combined. The body carries max_bytes.
413too_many_partsToo many elements in the multipart body: 20 files, 10 fields, 32 parts in total. The body carries limit (the bound that was crossed) and max.
415unsupported_media_typeThe request Content-Type cannot be parsed. Conversions are sent as multipart/form-data; everything else lands here — a raw body (application/pdf, application/octet-stream…), application/json, application/x-www-form-urlencoded, a missing header, or multipart/form-data without a boundary. The refusal happens before the body is read. The response carries the received type (received) and the list of parsable types (accepted).
415unsupported_contentFile content does not match the tool. The type is determined from CONTENT, not from the filename extension: a valid PDF is accepted even without an extension, and a file renamed to .pdf is rejected. The extension only settles what the content cannot: .doc/.xls/.ppt, plain text and CSV, Pages and Numbers. Numbers and Keynote files are refused with detected_type iwork_numbers or iwork_keynote. The response carries file, the detected type (detected_type) and bytes.
422empty_fileEmpty file (0 bytes). The body carries file.
422password_protectedPassword-protected (encrypted) file on a tool that cannot decrypt it, including a DRM-protected EPUB book or a locked iWork document; remove the protection before converting. The body carries file.
422needs_password / wrong_passwordEncrypted PDF on a tool that can handle it: password missing, or refused by the file. Send the password field. Neither a job nor quota is consumed.
422too_many_pagesDocument beyond the page ceiling of the tool (see its entry), returned in max_pages.
422source_unreadableFile of the right type, but the engine cannot open it: corrupt, truncated, or non-standard structure.
429rate_limitedRate exceeded: 20 conversions per minute per key on POST /v1/convert/:tool, 300 requests per minute per IP on the other endpoints. The response carries retry_after (seconds) and the Retry-After header; the monthly quota is not consumed.
429quota_exceededQuota reached. On paid plans, the body carries quota_period_end, the next reset date: do not retry before it. On the Dev plan, both quota_period_end and period_end are null — the included conversions do not renew, and a trial is not billed — and the body carries upgrade, the plan that reopens access.
500conversion_failedThe engine failed. The body carries job_id and status: "failed". Quota is refunded: our own breakdowns are not billed.
500internal_errorBreakdown outside conversion. No detail is published — 5xx responses are masked server-side.
503server_busyConversion queue saturated (retry within 5 s — Retry-After header)
504conversion_timeoutEngine time budget exceeded. The body carries timeout_ms, and the job is failed. Quota is refunded.

Errors specific to one tool are described in its entry:

CodeErrorTool
400no_file_expectedurl-to-pdf
400password_too_short / password_too_longprotect-pdf
415unsupported_formatimage-to-pdf
422epub_blank_output / epub_too_longepub-to-pdf
422html_blank_outputhtml-to-pdf
422invalid_url / url_unreachable / url_http_error / url_blocked / url_blank_pageurl-to-pdf
422output_too_largepdf-to-image, split-pdf
422pdf_already_protectedprotect-pdf
422pdf_not_protectedunlock-pdf
422pdf_scanned_needs_ocr / pdf_too_many_pagespdf-to-word
422pdf_single_pagesplit-pdf
422ps_blank_outputps-to-pdf
422unsupported_characterswatermark-pdf

Integrations

SDK, OpenAPI and Postman

Use Conv2pdf with n8n

The official Conv2pdf node for n8n runs the 20 tools on the files that flow through your workflows, and converts a web page from its address. On a self-hosted n8n, open Settings > Community Nodes, select Install and enter n8n-nodes-conv2pdf, then create a Conv2pdf API credential with your key. Merging, job deletion, retries and use by the AI Agent: see the README on GitHub.

Use Conv2pdf with Zapier

The official Conv2pdf app on Zapier adds an action to your Zaps for each of the 20 tools. Connect it with your API key and map a file from a previous step, or give the address of a web page: the action returns the converted file and the quota of the key. Zapier gives a step 30 seconds, so very large files are better converted through the API directly. AI assistants such as Claude, ChatGPT and Cursor can also call these actions through Zapier MCP. The list of actions and how they behave are on GitHub.

Use Conv2pdf with an AI assistant (MCP)

The official Conv2pdf MCP server gives an AI assistant the 20 tools of the API, on the files of your computer and on web pages from their address: Claude Code, Claude Desktop, Cursor and any Model Context Protocol client that runs a local server. The assistant gives the path of a file; the server sends it to Conv2pdf, writes the result next to the original without ever overwriting an existing file, then deletes the job from Conv2pdf. It needs Node.js 22 or later, and your API key in the CONV2PDF_API_KEY environment variable.

In Claude Code:

claude mcp add --env CONV2PDF_API_KEY=cpdf_live_... --transport stdio conv2pdf -- npx -y conv2pdf-mcp

On Windows, put cmd /c before npx. In Claude Desktop, Cursor and the other clients configured with a JSON file:

{
  "mcpServers": {
    "conv2pdf": {
      "command": "npx",
      "args": ["-y", "conv2pdf-mcp"],
      "env": { "CONV2PDF_API_KEY": "cpdf_live_..." }
    }
  }
}

In Claude Code, the Conv2pdf plugin installs the same server with a skill that tells the assistant which tool to call, in which order, and what a call costs:

/plugin marketplace add conv2pdf/mcp
/plugin install conv2pdf@conv2pdf

Then ask for what you need: "convert report.docx to PDF", "merge these three PDFs", "compress scan.pdf and protect it with a password". The server exposes 13 tools: convert_to_pdf for office documents, images, HEIC photos and EPUB books, one tool per PDF operation, and get_quota to read the quota of the key. Each conversion counts in the quota like a call to the API. The Claude and ChatGPT web apps, which do not run a local server, go through Zapier MCP. Source and usage notes are on GitHub.

Privacy

Files (input and output) are deleted after 1 hour. The only exception on the service’s side: if a conversion fails, the uploaded file is kept for 72 hours to find the cause, then deleted. Only one thing can extend a converted file’s life, and it goes through the website: from the dashboard, the account holder can create a share link for a job — including one produced by the API — in which case the shared copy lives until the link expires (seven days at most on Free, thirty on Premium) or until it is revoked. No result caching is applied. All processing happens on OVHcloud servers in France. See our privacy policy for details.

Support

For any technical question, use our contact form (subject "Technical question"). Business and Custom plans: priority support with contractual SLA.