Developers

The Converterrr API

Convert files between 140+ formats from your own code. Send a URL or upload a file, and get the result back — by polling or with a signed webhook. Same engines as the web app: FFmpeg, ImageMagick, LibreOffice, Pandoc, Calibre and more, each job in its own isolated sandbox.

Get an API key API reference OpenAPI spec

Quickstart

The API is included in every paid plan, from $14/month. Create an API key in your dashboard, then create a job. The base URL is https://www.converterrr.com/api/v1.

curl https://www.converterrr.com/api/v1/jobs \
  -H "Authorization: Bearer $CONVERTERRR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "url": "https://example.com/slides.pptx" }, "output_format": "pdf" }'

A job moves from queued to processing to completed (or failed). Completed jobs include an output.download_url that stays valid until expires_at.

Authentication

Send your key in the Authorization header as a bearer token (or in x-api-key). Keys start with cvr_live_, are shown once when created, and can be revoked at any time. Keep them server-side — never ship them in a browser or mobile app.

Authorization: Bearer cvr_live_xxxxxxxxxxxxxxxxxxxxxxxx

API access requires a verified email address. Requests without a valid key return 401 unauthorized.

Uploading files

There are three ways to give us a file:

Field	Type	Description
input.url	JSON	Any public http(s) URL — including presigned S3/GCS links. We download it for you.
multipart file	form-data	Send the file in a `file` field together with `output_format`. Best for files under 4 MB.
input.upload_id	JSON	For large files: create a presigned upload, PUT the bytes, then reference the upload.

Large file upload

# 1. Ask for a presigned URL
curl https://www.converterrr.com/api/v1/uploads -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "filename": "interview.mov" }'
# → { "id": "upl_…", "upload_url": "https://…", "method": "PUT", "max_size": 1073741824 }

# 2. Upload the raw bytes (any HTTP client works)
curl -X PUT --upload-file interview.mov "$UPLOAD_URL"

# 3. Convert it
curl https://www.converterrr.com/api/v1/jobs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "input": { "upload_id": "upl_…" }, "output_format": "mp4" }'

Webhooks

Pass webhook_url when creating a job and we'll POST the job to it when it finishes. Failed deliveries (network errors or 5xx responses) are retried with exponential backoff.

Payload

{
  "type": "job.finished",
  "data": {
    "id": "cm3x9q2f80001",
    "status": "completed",
    "conversion": { "from": "pptx", "to": "pdf", "label": "PPTX → PDF" },
    "output": { "name": "slides.pdf", "size": 482113, "download_url": "https://…?download=1" },
    "credits": 2
  }
}

Every request carries a Converterrr-Signature header like t=1730822400,v1=…. Verify it with your webhook signing secret (shown on the API keys page) to make sure the request came from us:

Verify a webhook (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Errors

Errors use standard HTTP status codes and a consistent JSON body:

{ "error": { "code": "insufficient_credits", "message": "Not enough credits for this conversion." } }

Field	Type	Description
400 invalid_request		The body or parameters are invalid. The message says which field.
401 unauthorized		Missing, invalid or revoked API key.
402 plan_required		The account has no active paid plan. The API is included in every paid plan.
402 insufficient_credits		Not enough credits for this conversion.
403 email_unverified		Verify your email to use the API.
404 not_found		The job or upload doesn't exist (or isn't yours).
413 file_too_large		The file is larger than your plan allows.
429 rate_limited		Too many requests. Back off and retry.

Credits & limits

Field	Type	Description
Credits		1,500–20,000 per month depending on your plan, plus credit packs that never expire.
Cost per job		1 credit (2 for Office, eBook and PDF→Word conversions), +1 per extra minute of processing.
Failed jobs		Never charged — credits are refunded automatically.
Rate limit		120 requests per minute per API key.
File size		1 GB to 10 GB per file depending on your plan.
Retention		Outputs are deleted after 24–168 hours depending on your plan.

Check your remaining credits at any time with GET /account. See pricing for plans and packages.