# 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](https://convert.dev/docs/api/jobs.md) 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`.

Response:

```json
{
  "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://…"}]
}
```

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.

## 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](https://convert.dev/docs/errors.md) 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](https://convert.dev/docs/api/waiting.md).

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](https://convert.dev/docs/api/waiting.md#idempotency).
