Skip to main content
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

GoalHow jobs help
Keep your app responsiveYour request returns once files are uploaded and the job is queued.
Process many filesWorkers can handle larger batches within the limits of the user’s plan.
Track progressPoll job status to show pending, processing, completed, or failed states.
Build workflowsCombine 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.