PrivConvert API

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.

Authentication

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

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 350+ tools.

Parameters

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:

Errors return JSON instead of a file:

{
  "error": {
    "code": "file_too_large",
    "message": "File exceeds your plan’s size limit."
  }
}

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} is capped at 100 MB by our edge network. To convert larger files — up to your plan’s max file size (Growth & Scale: 500 MB) — upload the file in parts of under 100 MB each. It is a simple three-step flow, authenticated with the same Bearer key:

1. Initialise the session — declare the total size, number of parts, filename and tool.
2. Upload each part in order (index 0…N-1), each under 100 MB.
3. Convert — the server reassembles the file in memory, converts it, and streams the result back. It counts as one conversion against your quota.

POST /api/upload-init  ·  POST /api/upload-chunk  ·  POST /api/convert-chunked

# Convert a 300 MB PDF by uploading it in parts (bash).
# Requires a Growth or Scale key. 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 350+ available slugs:

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, ebook, archive, mesh, font, spreadsheet, presentation, medical).

curl https://privconvert.com/api/tools?category=image

{
  "version": "1",
  "base_url": "https://privconvert.com/api",
  "count": 76,
  "categories": ["archive", "data", "document", "…"],
  "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 and resets on the first of each month. Beyond your rate limit or quota, requests return 429 with a Retry-After header.

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.

Privacy & data handling

Privacy is the product. Every file you send to the API is:

• Processed entirely in RAM — never written to disk.
• Deleted from memory the instant the converted file is returned.
• Never logged, never used for training, never shared.
• Covered by a signed DPA on Enterprise plans.