Guide

Jobs & lifecycle

How jobs, conversions, inputs and outputs fit together.

Everything in the API revolves around the job. A job groups the files you send in, the conversions to run, and the files produced.

The data model

Job — the unit of work. Has an id, a token, a status, and the flags below.
input[] — the source files (remote URL, upload, base64, cloud…). See Importing files.
conversion[] — what to produce: a category + target + options.
output[] — the resulting files, each with a download uri.

Unlike a task-graph API, api2convert jobs are flat: a job has inputs, conversions and outputs as parallel lists rather than a dependency graph.

Job flags

Flag	Purpose
`process`	Start the job immediately after creation. If `false`, the job stays `incomplete` until you PATCH it with `process: true`.
`fail_on_input_error`	Fail the whole job if any input cannot be fetched.
`fail_on_conversion_error`	Fail the whole job if any conversion errors.
`callback`	URL notified when the job finishes — see Webhooks.

Statuses

Typical progression: incomplete → ready → running → completed (or failed). The authoritative list is available at GET /v2/statuses.

Building a job incrementally

Instead of one big POST, you can build a job step by step and start it last:

POST   /v2/jobs                      → create (process: false)
POST   /v2/jobs/{id}/input           → add input file(s)
POST   /v2/jobs/{id}/conversions     → add a conversion
PATCH  /v2/jobs/{id}                  → { "process": true }  (start)
GET    /v2/jobs/{id}                  → poll status / read output
GET    /v2/jobs/{id}/history          → audit trail of the job

Modifying a job after creation (PATCH)

While a job is still incomplete — created but not yet started — you can adjust its parts with PATCH. Authenticate with the x-oc-api-key header.

Endpoint	What you can change
`PATCH /v2/jobs/{id}`	Start the job (`process: true`), or update job-level fields such as `callback`, `notify_status`, `fail_on_input_error` and `download_passwords`.
`PATCH /v2/jobs/{id}/input`	Reorder inputs (`position`), and set per-input `slide_duration` (slideshow timing) or `resize_handling`.
`PATCH /v2/jobs/{id}/input/{input-id}`	Set the `decrypt_password` for a single password-protected input.
`PATCH /v2/jobs/{id}/conversions/{conversion-id}`	Change a conversion's `options`, or insert/update/delete file `metadata`.
`PATCH /v2/jobs/{id}/output/{output-id}`	Rename the output (`filename`) or set a `download_password`.

Reorder inputs

When several inputs are combined into one file, the output order follows each input's position (1-based). After the inputs are added, send one PATCH with the new positions — an array of { id, options: { position } }, where id is the input id returned when it was added:

curl -X PATCH https://api.api2convert.com/v2/jobs/<job-id>/input \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": "<cover-input-id>",  "options": { "position": 1 } },
    { "id": "<report-input-id>", "options": { "position": 2 } }
  ]'

position is 1-based and must be between 1 and the number of inputs. The same endpoint also accepts slide_duration (0.1–120 seconds, for slideshows) and resize_handling (keep_aspect_ratio or stretch).

Change a conversion's options

Adjust a conversion you already added — without recreating the job — by patching it with the conversion id returned when it was created:

curl -X PATCH https://api.api2convert.com/v2/jobs/<job-id>/conversions/<conversion-id> \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "options": { "quality": "ebook" } }'

Managing jobs

GET /v2/jobs — list your jobs (paginated, 50 per page; filter with ?status=).
DELETE /v2/jobs/{id} — cancel/remove a job.