Migrating from another conversion API

Our API takes ConvertAPI-style requests: a multipart form posted to a convert/{from}/to/{to} path, with the key in an Authorization: Bearer header, answered with the same JSON field names. Code that goes through ConvertAPI's Python or Node.js client library can't move yet. This page lists what carries over, what doesn't, and how to test before you switch traffic.

If your current API has a different request shape, such as JSON bodies, upload-then-convert jobs or input from a URL, moving means rewriting those calls against Requests. None of those shapes work here yet. For prices and a feature comparison, see how we compare with ConvertAPI.

Who can switch by changing the URL and the key

You can, if all four of these hold:

1. Your code sends the HTTP request itself, with the file in a multipart/form-data body, the way ConvertAPI's curl examples do.
2. Every path you call exists here. Of ConvertAPI's 328 documented endpoints, 279 work here on the same path and do the same job (counted on 2026-11-02). Check your paths against our list.
3. Every option you set is one we apply, or is left at ConvertAPI's default. Anything else gets a 400 that names the option, as described below.
4. Each request, files and fields together, fits your plan's upload size. No plan takes more than 100 MB (Limits).

Then two things change, the URL and the key:

Note the /v2 segment at the start of our path. A path without it, such as /convert/docx/to/pdf, gets a 404.

In a curl command the change is two lines:

-curl -sS -X POST https://v2.convertapi.com/convert/docx/to/pdf \
-  -H "Authorization: Bearer $CONVERTAPI_TOKEN" \
+curl -sS -X POST https://api.pdfconversionapi.com/v2/convert/docx/to/pdf \
+  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
   -F File=@report.docx \
   -F StoreFile=true

This is the new command, and the response it returned when we ran it on 2026-11-03 against the API server running locally in a container, with only the base URL changed (the JSON is formatted for reading, and the host in Url is ours):

curl -sS -X POST https://api.pdfconversionapi.com/v2/convert/docx/to/pdf \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@report.docx \
  -F StoreFile=true

{
  "ConversionCost": 1,
  "ConversionTime": 0.049,
  "Files": [
    {
      "FileName": "report.pdf",
      "FileExt": "pdf",
      "FileSize": 82830,
      "Url": "https://api.pdfconversionapi.com/v2/d/9eff2c1f94a5025b610bd1c86635e1f1/report.pdf",
      "FileId": "9eff2c1f94a5025b610bd1c86635e1f1"
    }
  ]
}

The fields are the ones ConvertAPI uses: ConversionCost, ConversionTime, and Files with FileName, FileExt and FileSize, plus either FileData (the file, base64-encoded) or, with StoreFile=true, Url and FileId. The input file is our 3-page test document, saved as report.docx.

What else is different

Requests

• Multipart only. A body sent as application/x-www-form-urlencoded or as JSON gets a 400. This one error has a plain-text body instead of JSON:

  Output

  Invalid `boundary` for `multipart/form-data` request

• No upload step. There is no /upload endpoint, and a FileId from one response can't be the input of the next request. Send the file's bytes in every request.

• No input from a URL. A URL in the File field is read as the file's contents, not downloaded. HTML conversions refuse the Url parameter with a 400.

• The key goes in the header only. A key in the query string (?Secret= or ?Token=) is not read, and the request gets a 401.

• Parameters go in the form only. Parameters in the URL's query string are not read, so ?PageRange=1-2 has no effect. Send every parameter as a form field.

• Timeout is accepted and ignored. Every conversion gets up to 120 seconds of engine time, then the request returns 504. Give your HTTP client a timeout of a few minutes; our examples use 240 seconds.

• Requests up to your plan's upload size, all files and fields together, and 100 MB at most on any plan. The edge network in front of our API can answer a larger request with its own 413 response, which is not JSON.

• Plan limits. Your plan sets your conversions a month, upload size and conversions at once. The Free plan allows 250 conversions a month, files up to 10 MB and 1 conversion at a time. Over a limit you get a 413 or a 429 whose message says which limit you reached (Limits).

• 600 requests a minute per account. Over that, you get a 429 with Retry-After: 10.

• No CORS headers. Call the API from your server, not from a browser.

Paths

• 279 of 328. Of ConvertAPI's 328 documented endpoints, 279 work here on the same path and do the same job.
• The general paths work. file/to/pdf, office/to/pdf and file/to/md take the format from the uploaded file's name, so report.docx sent to file/to/pdf converts as it would on docx/to/pdf. file/to/pdf takes every format we convert to PDF, but not all the ones ConvertAPI lists for it: DjVu, DWF, DWFX, EPS, Keynote, PRN and PostScript files get a 404, such as conversion from ps to pdf is not supported. Conversions has the details.
• pdf/to/extract has the same path and a different job. ConvertAPI's extracts data from documents with AI. Ours copies the pages you list in PageRange into a new PDF.
• The other 48 return 404. They include PostScript and EPS input, DjVu, DWF, Keynote, document templates and comparison, and AI services such as redaction. The comparison page groups them.
• Format aliases such as jpeg and tif work in the path. Conversions lists them.

Results

• ConversionCost is always 1 per request, however many pages or files come back. Only successful conversions count toward your plan's month; failed requests don't.
• Without StoreFile, nothing is stored. The converted file comes back in FileData.
• With StoreFile=true, the link works for 3 hours. Stored files are kept in object storage in the US jurisdiction. A job that runs every 15 minutes deletes files whose links have expired, and a storage rule that removes anything older than one day is the backstop. To delete a file sooner, send DELETE /v2/d/{FileId} with a key of the account that created it. See Stored files.
• Errors are JSON with the HTTP status in Code and a sentence in Message, for example {"Code":404,"Message":"conversion from ps to pdf is not supported"}. If your error handling looks for particular codes or messages, test it against ours. Errors lists them.

Defaults that differ

Three of our defaults differ from the ones ConvertAPI documents. We apply all three parameters, so if your output depends on one, send its value in the request:

Not supported yet

• ConvertAPI's client libraries. We read the source of its Python and Node.js clients on 2026-11-01. Both upload each file to /upload first, then send the conversion as application/x-www-form-urlencoded with the returned FileId. We support neither step, so those clients fail here. We have not checked the clients for other languages; test before you assume they work.
• Client libraries of our own. Any HTTP client that can send a multipart form works. Requests has examples in curl, Python and Node.js.
• Asynchronous conversions and webhooks. Every request waits for its result.
• Input from a URL, and passing one result into the next request by FileId.
• Billing. Only the Free plan is self-serve until billing opens. For higher limits before then, write to sales@pdfconversionapi.com.
• Team accounts. Each account belongs to one verified email address.
• A dashboard beyond the key page, and a status page. The key page at app.pdfconversionapi.com lets you replace your key, see this month's usage and delete your account. GET /v2/usage returns this month's count from the API.

Options we don't apply get a 400

ConvertAPI documents a set of options for each conversion, most with a default value. We check requests against that same list. When a request sets one of those options to something other than its default and our converter doesn't apply it, the request fails with a 400 that names every such option, and no file comes back.

curl -sS -X POST https://api.pdfconversionapi.com/v2/convert/docx/to/pdf \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@report.docx \
  -F PageRange=1-2 \
  -F Pdfa=true

{"Code":400,"Message":"PageRange, Pdfa are not supported yet for DOCX → PDF"}

How the check works:

• Default values pass. Pdfa=false is ConvertAPI's default for DOCX to PDF, so a request with it converts normally. So do ConvertAPI's named defaults, such as PageOrientation=default on image to PDF, Preset=none on image to SVG and CompressionLevel=Medium on file/to/zip. The comparison with ConvertAPI's default is loose: 1 matches true, 200.0 matches 200, and A4 matches a4. Options we apply follow their own rules, so a whole-number option such as ImageQuality refuses 75.0.
• Some converters refuse an option before they start, for example with AutoFitColumns is not supported yet for XLSX files. The general check runs after the converter finishes, so that 400 can take as long as the conversion itself.
• A parameter ConvertAPI doesn't document for that conversion is ignored. If a setting seems to have no effect, check the spelling of its name.

When you get one of these 400s, you can drop the option and accept our default, keep that request on your current provider, or write to support@pdfconversionapi.com and tell us which option you need. Our guides list the options each common conversion applies, for example DOCX to PDF and PDF to JPG.

Test checklist

Work through these with your own files before you move traffic. You need a key: sign in at app.pdfconversionapi.com to get a free one. The Free plan allows 250 conversions a month, files up to 10 MB and 1 conversion at a time, so test with files that fit, or write to sales@pdfconversionapi.com for higher limits before billing opens.

1. Find out how your code calls the API. If it imports ConvertAPI's client library, it won't work here yet. If it builds the request with an HTTP client, go on.

2. Check every path with the script in Conversions, and add /v2 in front of /convert.

3. Replay one request of each kind with the options your code sends, and look for 400s that name an option. This script sends three requests and saves each result in migration-test/:

   Python

   import base64
   import os
   import pathlib
   
   import requests
   
   BASE = "https://api.pdfconversionapi.com/v2/convert"
   HEADERS = {"Authorization": f"Bearer {os.environ['PDFCONVERSIONAPI_KEY']}"}
   
   # One line per kind of request your code sends today: path, input file, form fields.
   REQUESTS = [
       ("docx/to/pdf", "report.docx", {"UpdateTableOfContents": "true"}),
       ("pdf/to/jpg", "season-guide.pdf", {"ImageResolution": "200", "PageRange": "1"}),
       ("docx/to/pdf", "report.docx", {"PageRange": "1-2"}),
   ]
   
   out = pathlib.Path("migration-test")
   out.mkdir(exist_ok=True)
   
   for number, (path, name, fields) in enumerate(REQUESTS, start=1):
       with open(name, "rb") as f:
           response = requests.post(
               f"{BASE}/{path}", headers=HEADERS, files={"File": f}, data=fields, timeout=240
           )
       if "application/json" not in response.headers.get("content-type", ""):
           print(number, response.status_code, path, "(not JSON)", response.text[:80])
           continue
       result = response.json()
       if not response.ok:
           print(number, response.status_code, path, result["Message"])
           continue
       for file in result["Files"]:
           (out / f"{number}-{file['FileName']}").write_bytes(base64.b64decode(file["FileData"]))
       sizes = ", ".join(f"{file['FileName']} ({file['FileSize']} bytes)" for file in result["Files"])
       print(number, response.status_code, path, sizes)

   To run it as written, save our test document as report.docx and our sample PDF as season-guide.pdf. It printed this on 2026-11-04 (Python 3.14.2, requests 2.34.2, the API server running locally in a container):

   Output

   1 200 docx/to/pdf report.pdf (82830 bytes)
   2 200 pdf/to/jpg season-guide-1.jpg (305519 bytes)
   3 400 docx/to/pdf PageRange is not supported yet for DOCX → PDF

4. Compare the outputs with the files your current provider returns for the same inputs: page count, page size, fonts and image dimensions. The engines are different, so expect some differences. Our guides show a sample input and the output we produced for common conversions.

5. Send the defaults that differ (table above) if your output depends on them.

6. Check your error handling. Code is the HTTP status. Two errors are not JSON: the plain-text 400 for a body that isn't multipart, and the edge network's 413 for a request over 100 MB (Errors). Retry a 429 or a 503 after the number of seconds in its Retry-After header. A 429 can come from the rate limit, your plan's conversions at once, or a used-up month; the message says which, and on a used-up month Retry-After runs to the first day of next month (UTC).

7. Download stored files within 3 hours of the response, or don't set StoreFile and read FileData instead.

8. Keep the base URL and the key in configuration, not in code, so you can move a request back if it fails here.

ConvertAPI is a trademark of its owner. pdfconversionapi.com is not affiliated with it.