Async Jobs

Use jobs when a batch should be processed by the worker queue instead of blocking the request. The jobs API uploads source files, creates a queued job record, and lets Convertly workers handle conversion or compression outside the request lifecycle.

Jobs are storage-backed because workers need persisted source files. For storage-free processing, use synchronous POST /api/convert or POST /api/compress.

What jobs achieve

Goal	How jobs help
Keep your app responsive	Your request returns once files are uploaded and the job is queued.
Process many files	Workers can handle larger batches within the limits of the user’s plan.
Track progress	Poll job status to show pending, processing, completed, or failed states.
Build workflows	Combine jobs with webhooks to continue work after conversion completes.

Create a job

curl -X POST "https://convertly.sh/api/jobs" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "jobType=convert" \
  -F "saveToStorage=true" \
  -F "files=@./input.png" \
  -F 'formats=["webp"]' \
  -F 'compressions=[82]' \
  -F 'resizes=["original"]' \
  -F "createArchive=false"

The response:

{
  "jobId": "a755a89a-3a63-4f3e-88ff-7fef50d42d7d",
  "status": "pending"
}

Poll status

curl "https://convertly.sh/api/jobs/a755a89a-3a63-4f3e-88ff-7fef50d42d7d" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

Job statuses include pending, processing, completed, and failed.

Job lifecycle

Pending

The API accepted the files, stored them, and queued the worker task.

Processing

A worker picked up the job and is updating progress.

Completed or failed

Results or errorMessage are available from GET /api/jobs/{id}.

Cancel a queued job

curl -X DELETE "https://convertly.sh/api/jobs/a755a89a-3a63-4f3e-88ff-7fef50d42d7d" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

Processing, completed, and failed jobs cannot be cancelled.

Build Flows

Image CDN

AI Agents

What jobs achieve

Create a job

Poll status

Job lifecycle

Cancel a queued job

​What jobs achieve

​Create a job

​Poll status

​Job lifecycle

​Cancel a queued job

What jobs achieve

Create a job

Poll status

Job lifecycle

Cancel a queued job