Concepts
Jobs and conversions
Everything convert.dev does to a file is a job. A job runs conversions whose versions are fixed, and the files it makes last a day.
One job, one task
A job converts, reads or edits. Writing a document is a conversion too, from Markdown or HTML to a format people open.
A read is a conversion with refs. An edit is a conversion from a format to the same format with edit. One job carries refs or edit, not both.
cv convert, cv read and cv edit each run a job. cv uploads the file, starts the job at https://api.convert.dev/v1/jobs, waits for it and saves what it made. See Jobs for every field.
A conversion has a version
Each conversion from one format to another, such as docx>pdf, is its own unit. Only the conversions cv targets lists exist, and each one says what it keeps and what it drops.
Each conversion has a version. It changes whenever anything that can change the result changes, such as its code, the engine it calls or a file it uses. A job lists the conversions it ran and their versions in transforms.
So two results with the same versions came from the same conversion. When a result looks different from last week's, compare the versions first.
{ "object": "job", "status": "done", "inputs": [{"id": "file_01JC9W…", "name": "lease.docx", "format": "docx"}], "transforms": [{"id": "docx>pdf", "version": "c992cd73"}], "outputs": [{"object": "file", "name": "lease.pdf", "url": "https://…"}]}Two kinds of failure
A job is checked before it starts. The conversion is picked from the file's format and your options, without reading the rest of the file. So a request that cannot work fails at once: a format it cannot become, an option out of range, options that do not fit together.
Some failures show only in the file: it is damaged, it has a password, or it needs OCR. Those fail while the job runs, with a code such as input_corrupted, input_encrypted or ocr_required.
Each error says if the same request can work later, in retryable. See Error codes for what to do with each one.
A job's life
A job is queued, then running, and ends done, failed or canceled. It ends once, and its result does not change after that.
Wait for the end in the request, poll for it or stream it. See Waiting and retries.
convert.dev is not storage. Uploads and outputs are deleted after 24 hours. Save what you need.
Running it again
cv remembers what it uploaded and what it ran in ~/.cache/cv. The same local file is not uploaded twice, and the same conversion of it is not run twice.
It uses a past job again only while the conversions it ran still have the same versions. After a conversion changes, the same command runs a new job.
In the API, a retry with the same Idempotency-Key and the same request within 24 hours gets the first job back instead of a new one. See Waiting and retries.
Updated 3 November 2026