API Reference
PrivConvert API
A single REST endpoint for every conversion - images, documents, data, eBooks, fonts and archives. Files are processed entirely in memory and nothing is ever written to disk. Synchronous results are deleted the instant they are returned; async results are deleted the moment you collect them, or within 30 minutes.
Introduction
The PrivConvert API turns any file conversion on PrivConvert into a single authenticated POST request. It is designed for teams that handle sensitive documents - legal, medical, finance - and cannot send files to a service that stores them.
https://privconvert.com/apiHTTPS only (TLS 1.3)Bearer API keymultipart/form-dataBinary file streamAuthentication
Every request must include your secret API key as a Bearer token in the Authorization header. Keys are issued per account and look like pk_live_…. Keep them server-side - never expose a key in client-side code.
# Pass your key in the Authorization header
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx Quick start
Convert a Word document to PDF. The converted file streams straight back in the response body.
# Convert contract.docx → PDF
curl -X POST https://privconvert.com/api/convert/word-to-pdf \
-H "Authorization: Bearer pk_live_…" \
-F "[email protected]" \
-o contract.pdf Official SDKs
Open-source clients for Python, Node.js, PHP and Go, with no runtime dependencies. They split large files into parts for you, retry short rate-limit and busy responses, run async jobs and verify webhook signatures.
# Python 3.10+
pip install privconvert
# Node.js 18.17+
npm install github:toprivHQ/privconvert-node#v0.3.0
# PHP 8.1+
composer require privconvert/privconvert
# Go 1.22+
go get github.com/toprivHQ/privconvert-go from privconvert import PrivConvert
pc = PrivConvert() # reads PRIVCONVERT_API_KEY
pc.convert("word-to-pdf", "contract.docx").save("contract.pdf") Files in cloud storage can be converted in place: the SDK reads the file from your storage and writes the result back, using your own credentials. Your cloud keys are never sent to PrivConvert. The cloud is picked from the address, and source and destination can be in different clouds.
Works with
- Amazon S3
- Google Cloud Storage
- Azure Blob Storage
- Backblaze B2
- Cloudflare R2
Amazon S3, Google Cloud Storage, Azure, Backblaze B2 and Cloudflare R2 are trademarks of their respective owners.
# Uses the cloud libraries you already have, or: pip install "privconvert[cloud]"
pc.convert_storage("word-to-pdf", "s3://my-bucket/input.docx", "s3://my-bucket/output.pdf")
pc.convert_storage("word-to-pdf", "gs://my-bucket/input.docx", "gs://my-bucket/output.pdf")
pc.convert_storage("word-to-pdf", "az://acct/files/input.docx", "az://acct/files/output.pdf") Cloudflare R2, Backblaze B2 and other S3-compatible storage use an s3:// address with an S3 client pointed at the provider.
Cloudflare R2
Convert files in an R2 bucket and write the result back to R2. Create an R2 API token with read and write access to the bucket, and use your Cloudflare account ID in the endpoint. The file goes from R2 to PrivConvert and back from wherever your code runs, and your R2 keys stay with you.
import os, boto3
from privconvert import PrivConvert
r2 = boto3.client(
"s3",
endpoint_url=f"https://{os.environ['R2_ACCOUNT_ID']}.r2.cloudflarestorage.com",
aws_access_key_id=os.environ["R2_ACCESS_KEY_ID"],
aws_secret_access_key=os.environ["R2_SECRET_ACCESS_KEY"],
region_name="auto",
)
pc = PrivConvert()
pc.convert_storage(
"word-to-pdf",
"s3://my-bucket/input.docx",
"s3://my-bucket/output.pdf",
s3_client=r2,
) The same works in Node.js, PHP and Go: pass an S3 client with the R2 endpoint and region set to auto. Each SDK's README on GitHub has the full example.
Source and full usage: privconvert-python, privconvert-node, privconvert-php and privconvert-go on GitHub.
Convert a file
POST /api/convert/{tool}
The {tool} path segment selects the conversion - for example word-to-pdf, png-to-jpg or json-to-csv. Send the source file as a file field in a multipart/form-data body. The same pattern works for all 450+ tools.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | The source file to convert, sent as multipart form data. |
quality | integer | No | Output quality 1-100 for image/PDF tools. The default varies by format - 90 for JPEG, 85 for WebP, 60 for AVIF. GET /api/tools reports the exact default for each tool. |
width | integer | No | Target width in pixels for resize-capable image tools. |
height | integer | No | Target height in pixels for resize-capable image tools. |
Response
On success (200) the response body is the converted file - a raw binary stream, not JSON. Read it from the body and write it to disk. Useful headers:
| Header | Example |
|---|---|
Content-Type | application/pdf |
Content-Disposition | attachment; filename="contract.pdf" |
X-Credits-Remaining | 4985 |
X-Sanitize-Report | {"javascript":2,"launch":1,"clean":false} |
X-Sanitize-Report is returned by sanitize-pdf and sanitize-svg only. It is a JSON object counting what was removed from the file, so a pipeline can log which uploads arrived carrying active content without keeping the original. "clean": true means nothing was found.
Errors return JSON instead of a file:
{
"error": {
"code": "file_too_large",
"message": "File exceeds your plan’s size limit."
}
}
Convert many files
POST /api/convert-batch runs one tool over up to 20 files in a single request and returns them as a ZIP. Same key, same tool names as the single-file endpoint.
curl -X POST https://privconvert.com/api/convert-batch \
-H "Authorization: Bearer pk_live_..." \
-F "tool=png-to-jpg" \
-F "[email protected]" -F "[email protected]" -F "[email protected]" \
-o converted.zip | Field | Required | Notes |
|---|---|---|
tool | Yes | Tool id, e.g. png-to-jpg. An unknown id returns 400. |
files | Yes | Repeat the field once per file. More than 20 returns 400. |
quality | No | Applies to every file in the request. Defaults to 85. |
start, end | No | Page range, for tools that take one. Applied to each file individually. |
How it counts against your plan
This is the reason to use it. A batch is one request against your per-minute rate limit regardless of how many files it carries, while each converted file counts as one conversion against your monthly quota. Twenty files sent as a batch cost one of your rate-limit slots; sent individually they cost twenty. Either way the quota cost is identical, so batching buys you throughput, not cheaper conversions.
The whole request must fit in 100 MB, and your plan's per-request size cap applies to the total as well. Over either limit the response is 413.
When some files fail
One unreadable file does not fail the batch. Everything that converted is still returned, and the ZIP gains a PRIVCONVERT-ERRORS.txt listing what was skipped and why. The status is still 200, so check the headers rather than the status code:
| Header | Example | Meaning |
|---|---|---|
X-Converted-Count | 18 | Files in the ZIP. |
X-Failed-Count | 2 | Files skipped. |
X-Partial-Success | 1 | Present only when something was skipped. |
If nothing converted there is no partial result worth shipping, so the response is 400 with the first failure reason instead of an empty archive.
A single file above your plan's size cap belongs on the chunked upload endpoint instead - batch is for many ordinary files, not for one large one.
Async jobs
POST /api/jobs/{tool}
Every tool that works on /api/convert/{tool} also works asynchronously: submit the file, get a job id back immediately, and collect the result when it is ready - by polling or by webhook. Use it for long conversions, pipelines that must not block on an open HTTP connection, and burst traffic (a submitted job waits out momentary server load and retries internally instead of failing). The request format, the optional parameters and the quota cost are identical to the synchronous endpoint.
The 202 response carries two identifiers with different jobs:
| Field | Example | What it is |
|---|---|---|
id | job_f3a81c… | The public job id. Safe to log and to reference in URLs; appears in webhook payloads. |
key | pjk_Zk83… | The secret job key, returned exactly once. We store only a hash of it. It authorizes the download (sent as an X-Job-Key header, never in a URL) and it is the secret your webhook signature is derived from. Treat it like a password for this one job. |
GET /api/jobs/{id} · GET /api/jobs/{id}/download · DELETE /api/jobs/{id}
Status answers processing, finished (with output metadata, a download path and an expires_at timestamp) or failed (with the same error object the synchronous endpoint would have returned - an async failure is never a mystery). All three endpoints require your API key; jobs belong to your account and are invisible to anyone else.
# 1. Submit. The 202 response carries the job id and the ONE-TIME key.
curl -s -X POST https://privconvert.com/api/jobs/word-to-pdf \
-H "Authorization: Bearer pk_live_…" \
-F "[email protected]"
# -> {"id":"job_…","key":"pjk_…","status":"processing","poll":"/api/jobs/job_…"}
# 2. Poll until finished or failed.
curl -s https://privconvert.com/api/jobs/job_… \
-H "Authorization: Bearer pk_live_…"
# 3. Download. The job key travels in a header, never in a URL.
curl -s https://privconvert.com/api/jobs/job_…/download \
-H "Authorization: Bearer pk_live_…" \
-H "X-Job-Key: pjk_…" \
-o contract.pdf import time
import requests
B = "https://privconvert.com/api"
H = {"Authorization": "Bearer pk_live_…"}
with open("contract.docx", "rb") as f:
job = requests.post(f"{B}/jobs/word-to-pdf",
headers=H, files={"file": f}).json()
# Store job["key"] now: it is returned exactly once.
while True:
state = requests.get(f"{B}/jobs/{job['id']}", headers=H).json()
if state["status"] in ("finished", "failed"):
break
time.sleep(2)
if state["status"] == "finished":
r = requests.get(f"{B}/jobs/{job['id']}/download",
headers={**H, "X-Job-Key": job["key"]})
r.raise_for_status()
with open("contract.pdf", "wb") as out:
out.write(r.content)
else:
print("conversion failed:", state["error"]["message"]) import { readFile, writeFile } from "node:fs/promises";
const B = "https://privconvert.com/api";
const H = { Authorization: "Bearer pk_live_…" };
const form = new FormData();
form.append("file", new Blob([await readFile("contract.docx")]), "contract.docx");
const job = await (await fetch(`${B}/jobs/word-to-pdf`, {
method: "POST", headers: H, body: form,
})).json();
// Store job.key now: it is returned exactly once.
let state;
do {
await new Promise((r) => setTimeout(r, 2000));
state = await (await fetch(`${B}/jobs/${job.id}`, { headers: H })).json();
} while (state.status === "processing");
if (state.status === "finished") {
const res = await fetch(`${B}/jobs/${job.id}/download`, {
headers: { ...H, "X-Job-Key": job.key },
});
await writeFile("contract.pdf", Buffer.from(await res.arrayBuffer()));
} else {
console.error("conversion failed:", state.error.message);
} Result retention
While a result waits for pickup it is held in RAM only, AES-256-GCM encrypted with a key derived from your job key - which we do not retain, so a stored result is unreadable without the key you hold. The result is kept for 30 minutes after the conversion finishes (re-downloadable within that window), then deleted. DELETE /api/jobs/{id} wipes it immediately. To be precise about what this is and is not: the conversion itself necessarily processes your file in server memory, exactly like the synchronous API; the encryption covers the stored result awaiting pickup.
404 for a job you did not delete, resubmit it. A finished result past expires_at answers 410.
Webhooks
Pass a webhook_url form field when submitting a job and we will POST a JSON notification to it when the job finishes or fails - no polling loop needed. The URL must be https on port 443 and publicly reachable; private and internal addresses are refused at submission. Deliveries originate from Cloudflare network addresses, not from a fixed server IP.
# Delivery: POST to your URL
Content-Type: application/json
User-Agent: PrivConvert-Webhooks/1.0
X-PrivConvert-Signature: t=1760000000,v1=609fa0d5493200…
{
"event": "job.finished",
"event_id": "evt_6c0f…",
"id": "job_f3a81c…",
"status": "finished",
"tool": "word-to-pdf",
"created_at": 1760000000,
"output": { "filename": "contract.pdf", "mime": "application/pdf" },
"download": "https://privconvert.com/api/jobs/job_f3a81c…/download",
"expires_at": 1760001800
} A failed job sends "event": "job.failed" with the error object instead of output/download. The payload never contains file content and never contains your job key: downloading still requires your API key plus the X-Job-Key header, so a webhook endpoint (or anything logging it) learns nothing it can use alone.
For complete receiving endpoints in Python (Flask) and Node.js (Express), see the full webhooks guide.
Delivery, retries and idempotency
- Any
2xxfrom your endpoint acknowledges delivery. Respond quickly and process afterwards. - Non-2xx or no answer: up to 4 attempts over roughly 45 seconds. The
event_idand body stay byte-identical across attempts; the signature is re-issued with a fresh timestamp on each one. - Deduplicate on
event_id: if you have processed anevent_idbefore, acknowledge and skip. That makes duplicate deliveries harmless. - A webhook that cannot be delivered never affects the job itself: the result stays available for polling and download for the full retention window.
Verifying signatures
Every delivery is signed so your endpoint can prove it came from us and is fresh. The X-PrivConvert-Signature header has the form t=<unix timestamp>,v1=<hex hmac>, and verification takes three steps:
- Derive the signing key from the job key you stored at submission:
signing_key = SHA-256("pc-webhook-sig-v1|" + job_key). (The derivation exists so the signing key and the result-encryption key are never the same bytes.) - Compute
HMAC-SHA256(signing_key, "<t>." + raw_body)over the exact raw request bytes and compare it tov1with a constant-time comparison. - Reject timestamps older than your tolerance (we recommend 5 minutes) to shut out replays. Legitimate retries always carry a fresh timestamp, so a tight window never rejects them.
import hashlib
import hmac
import time
def verify_webhook(job_key: str, signature: str, raw_body: bytes,
tolerance_s: int = 300) -> bool:
"""signature is the X-PrivConvert-Signature header value.
raw_body must be the EXACT request bytes, not re-serialized JSON."""
try:
parts = dict(p.split("=", 1) for p in signature.split(","))
ts, v1 = int(parts["t"]), parts["v1"]
except (KeyError, ValueError):
return False
if abs(time.time() - ts) > tolerance_s:
return False # stale timestamp: possible replay
sig_key = hashlib.sha256(b"pc-webhook-sig-v1|" + job_key.encode()).digest()
expected = hmac.new(sig_key, f"{ts}.".encode() + raw_body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1) import { createHash, createHmac, timingSafeEqual } from "node:crypto";
/** signature is the X-PrivConvert-Signature header value.
* rawBody must be the EXACT request bytes, not re-serialized JSON. */
function verifyWebhook(jobKey, signature, rawBody, toleranceS = 300) {
const m = signature.match(/^t=(\d+),v1=([0-9a-f]{64})$/);
if (!m) return false;
const ts = parseInt(m[1], 10);
if (Math.abs(Date.now() / 1000 - ts) > toleranceS) return false; // replay guard
const sigKey = createHash("sha256")
.update("pc-webhook-sig-v1|" + jobKey).digest();
const expected = createHmac("sha256", sigKey)
.update(`${ts}.`).update(rawBody).digest("hex");
return timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
} Test vector
Run your implementation against these fixed inputs before going live. Both snippets above produce exactly this result.
# Inputs
job key pjk_testvector_do_not_use_0000000000000000000
timestamp 1760000000
raw body {"event":"job.finished","event_id":"evt_00000000000000000000000000000000","id":"job_000000000000000000000000","status":"finished","tool":"txt-to-pdf"}
# Expected signature
X-PrivConvert-Signature: t=1760000000,v1=609fa0d5493200864ae983137780d6fa6cfd7946953052fcaf4f6d4b8792803f Code examples
The same request in your language of choice. Swap the png-to-jpg slug for any tool.
curl -X POST https://privconvert.com/api/convert/png-to-jpg \
-H "Authorization: Bearer pk_live_…" \
-F "[email protected]" \
-o photo.jpg import requests
with open("photo.png", "rb") as f:
r = requests.post(
"https://privconvert.com/api/convert/png-to-jpg",
headers={"Authorization": "Bearer pk_live_…"},
files={"file": f},
)
r.raise_for_status()
with open("photo.jpg", "wb") as out:
out.write(r.content) import { readFile, writeFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("photo.png")]), "photo.png");
const res = await fetch("https://privconvert.com/api/convert/png-to-jpg", {
method: "POST",
headers: { Authorization: "Bearer pk_live_…" },
body: form,
});
if (!res.ok) throw new Error("Conversion failed: " + res.status);
await writeFile("photo.jpg", Buffer.from(await res.arrayBuffer())); <?php
$ch = curl_init("https://privconvert.com/api/convert/png-to-jpg");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer pk_live_…"],
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => ["file" => new CURLFile("photo.png")],
]);
file_put_contents("photo.jpg", curl_exec($ch));
curl_close($ch); // Uses OkHttp
OkHttpClient client = new OkHttpClient();
RequestBody body = new MultipartBody.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("file", "photo.png",
RequestBody.create(new File("photo.png"), MediaType.parse("image/png")))
.build();
Request request = new Request.Builder()
.url("https://privconvert.com/api/convert/png-to-jpg")
.header("Authorization", "Bearer pk_live_…")
.post(body)
.build();
try (Response response = client.newCall(request).execute()) {
Files.write(Paths.get("photo.jpg"), response.body().bytes());
} using var client = new HttpClient();
using var form = new MultipartFormDataContent();
var file = new ByteArrayContent(await File.ReadAllBytesAsync("photo.png"));
file.Headers.ContentType = new MediaTypeHeaderValue("image/png");
form.Add(file, "file", "photo.png");
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "pk_live_…");
var res = await client.PostAsync(
"https://privconvert.com/api/convert/png-to-jpg", form);
res.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync("photo.jpg", await res.Content.ReadAsByteArrayAsync()); file, _ := os.Open("photo.png")
defer file.Close()
var body bytes.Buffer
w := multipart.NewWriter(&body)
part, _ := w.CreateFormFile("file", "photo.png")
io.Copy(part, file)
w.Close()
req, _ := http.NewRequest("POST",
"https://privconvert.com/api/convert/png-to-jpg", &body)
req.Header.Set("Authorization", "Bearer pk_live_…")
req.Header.Set("Content-Type", w.FormDataContentType())
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := os.Create("photo.jpg")
io.Copy(out, res.Body) Large file uploads
A single POST to /api/convert/{tool} accepts files up to 100 MB. To convert larger files - up to your plan’s max file size (500 MB above 100,000 conversions a month) - upload the file in parts of under 100 MB each. It is a simple three-step flow, authenticated with the same Bearer key:
- Initialise the session - declare the total size, number of parts, filename and tool.
- Upload each part in order (index
0…N-1), each under 100 MB. - Convert - the server reassembles the file in memory, converts it, and streams the result back. It counts as one conversion against your quota.
POST in Quick start is simpler. Upload sessions are bound to your account and expire after 5 minutes of inactivity.
POST /api/upload-init · POST /api/upload-chunk · POST /api/convert-chunked
| Step | Endpoint | Form fields | Returns |
|---|---|---|---|
| 1 | /api/upload-init | total_size, total_chunks, filename, tool | { "upload_id": "…" } |
| 2 | /api/upload-chunk | upload_id, chunk_index, file (the chunk) | { "received": n, "total": N } |
| 3 | /api/convert-chunked | upload_id (+ optional quality, width, height, password) | Converted file (binary stream) |
# Convert a 300 MB PDF by uploading it in parts (bash).
# Requires a key above 100,000/mo. Splits, uploads, then converts.
KEY="pk_live_…"
FILE=big.pdf
TOOL=compress-pdf
CHUNK=$((95*1024*1024))
# 0. split into 95 MB parts
split -b $CHUNK -d "$FILE" part_
N=$(ls part_* | wc -l)
SIZE=$(stat -c%s "$FILE")
# 1. init
ID=$(curl -s https://privconvert.com/api/upload-init \
-H "Authorization: Bearer $KEY" \
-F total_size=$SIZE -F total_chunks=$N -F filename="$FILE" -F tool=$TOOL \
| jq -r .upload_id)
# 2. upload each chunk
i=0; for p in part_*; do
curl -s https://privconvert.com/api/upload-chunk \
-H "Authorization: Bearer $KEY" \
-F upload_id=$ID -F chunk_index=$i -F file=@"$p" > /dev/null
i=$((i+1))
done
# 3. convert + download
curl -s https://privconvert.com/api/convert-chunked \
-H "Authorization: Bearer $KEY" \
-F upload_id=$ID -o out.pdf
# Python - same three steps.
import math, requests
KEY, FILE, TOOL = "pk_live_…", "big.pdf", "compress-pdf"
CHUNK = 95 * 1024 * 1024
H = {"Authorization": f"Bearer {KEY}"}
B = "https://privconvert.com/api"
data = open(FILE, "rb").read()
chunks = [data[i:i+CHUNK] for i in range(0, len(data), CHUNK)]
uid = requests.post(f"{B}/upload-init", headers=H, data={
"total_size": len(data), "total_chunks": len(chunks),
"filename": FILE, "tool": TOOL,
}).json()["upload_id"]
for i, c in enumerate(chunks):
requests.post(f"{B}/upload-chunk", headers=H,
data={"upload_id": uid, "chunk_index": i},
files={"file": c})
r = requests.post(f"{B}/convert-chunked", headers=H,
data={"upload_id": uid})
open("out.pdf", "wb").write(r.content)
Available tools
Every server-side conversion uses the same /api/convert/{tool} pattern. A sample of the 450+ available slugs:
Images
png-to-jpgto-webpheic-to-jpgcompress-imageresize-image Documents
word-to-pdfexcel-to-pdfpdf-to-wordhtml-to-pdfmarkdown-to-pdf Data
json-to-csvcsv-to-jsonxml-to-jsonyaml-to-jsonjson-to-sql eBooks
epub-to-mobipdf-to-epubmobi-to-epubazw3-to-epub Fonts & archives
ttf-to-woff2otf-to-woff2rar-to-zip7z-to-zip See the full tool catalog for every supported conversion. If a tool exists on the site, it works over the API with the same slug.
List tools programmatically
GET /api/tools
A public, machine-readable catalog of every conversion the API exposes - ideal for building dynamic integrations without hard-coding slugs. No API key required. Filter with ?category= (e.g. image, document, data, audio, ebook, archive, mesh, font, spreadsheet, presentation, medical). Every response also carries the full categories list, so an integration can discover them rather than hard-code this one.
curl https://privconvert.com/api/tools?category=image {
"version": "1",
"base_url": "https://privconvert.com/api",
"count": 79,
"categories": ["archive", "audio", "data", "…"],
"tools": [
{
"id": "png-to-jpg",
"name": "PNG to JPG",
"category": "image",
"input": "png",
"output": "jpg",
"endpoint": "/api/convert/png-to-jpg",
"params": [{ "name": "quality", "type": "integer", "default": 90 }]
}
]
} Rate limits & quotas
Quota is counted per successful conversion. A subscription's monthly volume resets on its billing date each month; package credits are used once it runs out. Beyond your rate limit or quota, requests return 429 with a Retry-After header.
| Monthly volume | Rate limit | Concurrent jobs | Max request size |
|---|---|---|---|
| Up to 10,000 / mo | 60 req / min | 2 | 250 MB |
| 10,001 - 100,000 / mo | 120 req / min | 4 | 250 MB |
| Above 100,000 / mo | 300 req / min | 6 | 500 MB |
| Enterprise | Custom | Custom | Custom |
Rate limit and quota are shared across every key on your account, so rotating keys does not reset either. The three limits fail differently and are worth telling apart: exceeding the per-minute rate or the monthly quota returns 429 rate_limited, while exceeding concurrent jobs - conversions running at the same instant, not per minute - returns 429 concurrency_limited. The second one is not fixed by waiting longer between batches; it is fixed by running fewer requests in parallel.
Max request size is the ceiling for your account. Some tools have a lower limit of their own, between 6 MB and 100 MB: mostly text and data formats (CSV, JSON, YAML, SQL, subtitles) and SQLite databases (64 MB). Each tool page shows its limit. A larger file returns 400 with the limit in the message and is not charged. A chunked upload declares its size up front, so /api/upload-init refuses it immediately with 413 (file_too_large) before any data is sent.
Errors
The API uses conventional HTTP status codes. 2xx means success; 4xx means a problem with the request; 5xx means a problem on our side.
| Status | Code | Meaning |
|---|---|---|
200 | OK | Conversion succeeded. The body is the converted file. |
400 | bad_request | Malformed request - missing file, bad parameter, or unreadable input. |
401 | unauthorized | Missing or invalid API key. |
411 | length_required | No Content-Length header. Size limits are enforced before the body is read, so a declared length is mandatory. Every standard HTTP client sends one. |
413 | file_too_large | The uploaded file exceeds your plan’s size limit. |
415 | unsupported_type | The input file type is not valid for this tool. |
422 | conversion_failed | The file was read but could not be converted. |
429 | rate_limited | Per-minute rate or monthly quota exceeded. Slow down and retry after Retry-After. |
429 | concurrency_limited | Too many conversions running at once on your account. Reduce parallelism, then retry after Retry-After. |
500 | server_error | Unexpected error on our side. Safe to retry. |
503 | server_busy | The service is at capacity right now. Retry after Retry-After with backoff. |
Privacy & data handling
Privacy is the product. Every file you send to the API is:
- Processed entirely in RAM - never written to disk.
- Synchronous conversions: input and result are deleted from memory the instant the converted file is returned.
- Async jobs: the input is deleted from memory when the conversion finishes. The result waits for pickup encrypted (AES-256-GCM, key derived from your job key, which we do not retain) in RAM only, and is deleted after 30 minutes, or immediately on
DELETE /api/jobs/{id}. - Never logged, never used for training, never shared.
- Covered by a signed DPA on Enterprise plans.
The complete data-handling model, including how waiting async results are encrypted with a key only you hold and why webhooks carry no secrets, is documented in the API & webhook privacy guide.
Choose a plan and create your key in minutes.