Developers

API reference

All endpoints live under https://www.converterrr.com/api/v1 and return JSON. Authenticate with Authorization: Bearer <key>.

List formats

GET/formats

Every supported format and every conversion available through the API. No authentication required. Filter with ?from=png.

curl "https://www.converterrr.com/api/v1/formats?from=heic"

Response

{
  "object": "list",
  "formats": [{ "id": "heic", "name": "HEIC", "title": "High Efficiency Image Container", "category": "image", "mime": "image/heic", "extensions": ["heic"] }, …],
  "conversions": [{ "from": "heic", "to": "jpg", "engine": "imagemagick" }, …]
}

Create an upload

POST/uploads

Returns a presigned URL valid for one hour. PUT the raw file bytes to it, then pass the returned id as input.upload_id when creating a job.

Field	Type	Description
filename*	string	File name including extension, used to detect the input format.

Response

{
  "object": "upload",
  "id": "upl_dXBsb2Fkcy9hcGkv…",
  "filename": "interview.mov",
  "upload_url": "https://blob.vercel-storage.com/?pathname=…&vercel-blob-signature=…",
  "method": "PUT",
  "max_size": 104857600,
  "expires_at": "2026-11-05T15:02:11.204Z"
}

Create a job

POST/jobs

Starts a conversion, or a compression with operation: "compress" (same format in, smaller file out). Send JSON with an input URL or upload id, or multipart/form-data with a file field (≤ 4 MB).

Field	Type	Description
input.url	string	Public http(s) URL to download the file from.
input.filename	string	Override the file name (and detected format) for URL inputs.
input.upload_id	string	An id returned by POST /uploads.
input_format	string	Format id of the input. Detected from the file name when omitted.
output_format	string	Format id to convert to, e.g. pdf, mp4, webp. Required unless operation is compress.
operation	string	convert (default) or compress.
compression_level	string	light, balanced (default) or strong. Compression only.
target_size	integer \| string	Compress to at most this size: bytes, or "500kb" / "2mb" (decimal units). Overrides the level; lossless formats (archives, FLAC, SVG) can't hit a target.
options.quality	integer	1–100. Lossy images and video.
options.width / height	integer	Resize, keeping aspect ratio when only one is given.
options.keep_metadata	boolean	Keep EXIF/ID3 and other metadata. Default true.
options.video_bitrate_kbps	integer	Target video bitrate.
options.audio_bitrate_kbps	integer	Target audio bitrate.
options.sample_rate	integer	Audio sample rate in Hz.
options.fps	integer	Output frame rate (video, GIF).
options.dpi	integer	Render resolution for PDF/vector → image (72–600).
webhook_url	string	Receives a POST when the job finishes or fails.

Multipart upload

curl https://www.converterrr.com/api/v1/jobs \
  -H "Authorization: Bearer $KEY" \
  -F file=@photo.heic \
  -F output_format=jpg \
  -F 'options={"quality": 90}'

Compress a PDF to 2 MB

curl https://www.converterrr.com/api/v1/jobs \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "url": "https://example.com/report.pdf" }, "operation": "compress", "target_size": "2mb" }'

Returns 201 with a job object in the queued state. Compression jobs have operation: "compress" and a compression object; if the file is already as small as it gets, the original comes back unchanged.

Retrieve a job

GET/jobs/:id

Poll this endpoint every 1–2 seconds until status is completed or failed — or use a webhook instead.

Job object

{
  "id": "cm3x9q2f80001",
  "object": "job",
  "status": "completed",
  "source": "api",
  "conversion": { "from": "docx", "to": "pdf", "label": "DOCX → PDF" },
  "engine": "libreoffice",
  "input": { "name": "q3-report.docx", "size": 812331 },
  "output": {
    "name": "q3-report.pdf",
    "size": 401227,
    "url": "https://…blob.vercel-storage.com/outputs/…/q3-report.pdf",
    "download_url": "https://…blob.vercel-storage.com/outputs/…/q3-report.pdf?download=1"
  },
  "credits": 2,
  "error": null,
  "created_at": "2026-11-05T14:02:11.204Z",
  "started_at": "2026-11-05T14:02:11.950Z",
  "completed_at": "2026-11-05T14:02:15.318Z",
  "expires_at": "2026-11-05T15:02:11.204Z",
  "duration_ms": 3368
}

List jobs

GET/jobs

Field	Type	Description
limit	integer	1–100, default 25.
starting_after	string	Job id to paginate after (from the previous page's last item).
status	string	Filter by status.

Response

{ "object": "list", "data": [ { "id": "cm3x9q2f80001", "object": "job", … } ], "has_more": false }

Cancel or delete a job

DELETE/jobs/:id

Cancels a queued job (credits are refunded) or schedules a finished job's files for immediate deletion. Jobs that are already processing return 409 in_progress.

Account

GET/account

Credits and limits for the account that owns the API key.

Response

{
  "object": "account",
  "plan": "pro",
  "credits": { "balance": 4870, "subscription": 4370, "packages": 500, "daily_free_used": 0, "daily_free_limit": 0 },
  "limits": { "max_file_size_mb": 4096, "concurrency": 10 }
}