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
- Create an account (free, email — no password required)
- From your dashboard, create an API key (free Dev plan, 300 conversions included to test, valid 12 months, no renewal)
- 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
- Conversion:
POST /v1/convert/:toolanswers when the conversion is done, with ajob_idand adownload_url. - Download:
GET /v1/download/:jobId, for one hour. After that the input and the output are deleted, and the download returns410 file_expired. - Deletion, optional:
DELETE /v1/job/:jobIderases 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
| Limit | Value | Beyond |
|---|---|---|
| File size | 10 MB on the Dev plan, 200 MB on paid plans | 413 file_too_large |
| Files per conversion | 1 on the Dev plan (2 for merge-pdf), 20 on paid plans | 402 plan_limit_files |
| Request size | 220 MB, files and fields combined | 413 payload_too_large |
| Multipart elements | 20 files, 10 fields, 32 parts in total | 413 too_many_parts |
| Conversion rate | 20 per minute per key | 429 rate_limited |
| Rate on other endpoints | 300 requests per minute per IP | 429 rate_limited |
| File retention | 1 hour after the conversion | 410 file_expired |
| Pages, duration, output size | specific to each tool, see its entry | 422 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; theusedcounter 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_endisnull, and so isperiod_end: a trial is not billed). - Overage: a small overage is tolerated (
soft_cap_limit, +10%) before the429 quota_exceededblock. - 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_afterfield in seconds,Retry-Afterheader) and503 server_busy(within 5 s,Retry-Afterheader). - Do not retry before the reset:
429 quota_exceeded, untilquota_period_end; on the Dev plan, as after402 credits_expired, only a paid plan (upgrade) reopens access. - Never retry:
410 file_expiredand410 job_deleted, the resource is gone. - Fix the request or the file: the other
4xx. A refused parameter costs nothing. - Breakdowns:
500 conversion_failedand504 conversion_timeoutare refunded to the quota.
Every code, with the fields it carries, is described in Error codes.
Reference
Endpoints
| Endpoint | Purpose |
|---|---|
POST /v1/convert/:tool | Convert one or more files |
GET /v1/download/:jobId | Download the result |
GET /v1/job/:jobId | Read the status of a job |
DELETE /v1/job/:jobId | Delete a job and its file |
GET /v1/quota | Read the quota of the key, at no cost |
GET /v1/tools | List 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) | Input | Files | Output |
|---|---|---|---|
| Conversions | |||
image-to-pdf | PNG, JPG, WEBP, GIF, TIFF | 1 | |
heic-to-jpg | HEIC, HEIF | 1 | JPG |
heic-to-pdf | HEIC, HEIF | 1 | |
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 | 1 | |
epub-to-pdf | EPUB | 1 | |
xps-to-pdf | XPS, OXPS | 1 | |
ps-to-pdf | PS, EPS | 1 | |
html-to-pdf | HTML, HTM, XHTML | 1 | |
url-to-pdf | http/https address (url field) | 0 | |
pdf-to-word | 1 | DOCX | |
pdf-to-image | 1 | ZIP (1 image/page) | |
| PDF operations | |||
merge-pdf | 2 to 20 | ||
split-pdf | 1 | ZIP (1 PDF/page) | |
extract-pages | 1 | ||
compress-pdf | 1 | ||
rotate-pdf | 1 | ||
protect-pdf | 1 | ||
unlock-pdf | 1 | ||
watermark-pdf | 1 | ||
page-numbers-pdf | 1 | ||
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.
| Field | Required | Values | Default |
|---|---|---|---|
format | no | png, jpg | png |
password | no | password 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.
| Field | Required | Values | Default |
|---|---|---|---|
ranges | yes | e.g. 1-5,7,10-12; 11- runs to the last page, -4 starts from the first | — |
password | no | password 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
| Field | Required | Values | Default |
|---|---|---|---|
quality | no | low (72 DPI), medium (150 DPI), high (300 DPI) | medium |
password | no | password 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
| Field | Required | Values | Default |
|---|---|---|---|
rotation | yes | 90, 180, 270, in degrees, clockwise | — |
password | no | password 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.
| Field | Required | Values | Default |
|---|---|---|---|
password | yes | password to set, 6 to 64 characters | — |
prevent_print | no | on prevents printing | printing allowed |
prevent_copy | no | on prevents copying text | copying 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
| Field | Required | Values | Default |
|---|---|---|---|
text | yes | watermark text, 50 characters at most | — |
password | no | password 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
| Field | Required | Values | Default |
|---|---|---|---|
position | no | bottom-center, bottom-left, bottom-right | bottom-center |
format | no | full ("X of N"), simple (the number only, no total) | full |
password | no | password 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:
| Code | Error | Cause |
|---|---|---|
| 400 | not_enough_files / too_many_files | File count outside tool bounds. The body carries min and provided, or max. |
| 400 | field_required | Required 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. |
| 400 | invalid_rotation / invalid_page_range / invalid_quality / invalid_format | Parameter 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. |
| 400 | bad_request | Multipart 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. |
| 401 | missing_bearer_token / invalid_api_key / account_not_provisioned | Missing auth, invalid or revoked key, or a key with no API account attached. |
| 402 | plan_limit_files | More 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). |
| 402 | credits_expired | Dev plan trial credits past their validity date (12 months from when they were granted), whatever is left. The body carries expired_at and upgrade. |
| 403 | forbidden | Job belongs to another key |
| 404 | tool_not_found / job_not_found | Tool or job does not exist |
| 409 | job_not_ready | The job exists but has no output: conversion pending, failed or rejected. The body carries status (pending / failed / rejected). |
| 410 | file_expired / job_deleted | Resource is gone for good: 1 h TTL exceeded, or job removed via DELETE /v1/job/:jobId. Do not retry. |
| 413 | file_too_large | File 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. |
| 413 | payload_too_large | Whole request beyond 220 MB, files and fields combined. The body carries max_bytes. |
| 413 | too_many_parts | Too 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. |
| 415 | unsupported_media_type | The 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). |
| 415 | unsupported_content | File 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. |
| 422 | empty_file | Empty file (0 bytes). The body carries file. |
| 422 | password_protected | Password-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. |
| 422 | needs_password / wrong_password | Encrypted 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. |
| 422 | too_many_pages | Document beyond the page ceiling of the tool (see its entry), returned in max_pages. |
| 422 | source_unreadable | File of the right type, but the engine cannot open it: corrupt, truncated, or non-standard structure. |
| 429 | rate_limited | Rate 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. |
| 429 | quota_exceeded | Quota 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. |
| 500 | conversion_failed | The engine failed. The body carries job_id and status: "failed". Quota is refunded: our own breakdowns are not billed. |
| 500 | internal_error | Breakdown outside conversion. No detail is published — 5xx responses are masked server-side. |
| 503 | server_busy | Conversion queue saturated (retry within 5 s — Retry-After header) |
| 504 | conversion_timeout | Engine 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:
| Code | Error | Tool |
|---|---|---|
| 400 | no_file_expected | url-to-pdf |
| 400 | password_too_short / password_too_long | protect-pdf |
| 415 | unsupported_format | image-to-pdf |
| 422 | epub_blank_output / epub_too_long | epub-to-pdf |
| 422 | html_blank_output | html-to-pdf |
| 422 | invalid_url / url_unreachable / url_http_error / url_blocked / url_blank_page | url-to-pdf |
| 422 | output_too_large | pdf-to-image, split-pdf |
| 422 | pdf_already_protected | protect-pdf |
| 422 | pdf_not_protected | unlock-pdf |
| 422 | pdf_scanned_needs_ocr / pdf_too_many_pages | pdf-to-word |
| 422 | pdf_single_page | split-pdf |
| 422 | ps_blank_output | ps-to-pdf |
| 422 | unsupported_characters | watermark-pdf |
Integrations
SDK, OpenAPI and Postman
- Official PHP SDK:
composer require conv2pdf/php(repo and examples). - OpenAPI 3.0 specification (JSON) — to generate a client in another language, import it into a tool (Swagger, Insomnia…) or feed an agent.
- Postman collection — import it, set your key, convert a PDF in a minute.
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.