Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt

Use this file to discover all available pages before exploring further.

Convertly can accept archives as media inputs and can return generated outputs as downloadable archives. Use archive handling when customers upload folders of assets, when an agency needs one delivery bundle, or when your product needs to preserve a group of converted files as a single download.

​
What archive handling does

TaskHow it works
Convert archive formatsSend an archive to POST /api/convert and choose an archive output such as zip, tar, tgz, 7z, gz, bz2, or xz.
Process files inside ZIPsUpload a ZIP and choose a non-archive output format to extract supported files and convert them as a batch.
Package generated filesUse createArchive=true on async jobs when your app wants one grouped download for the completed outputs.
Download saved files as an archiveIn the dashboard file manager, users can archive selected stored files or folders.

​
Archive conversion

curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./client-assets.zip" \
  -F "format=tgz"

{
  "files": [
    {
      "filename": "client-assets.tgz",
      "mimeType": "application/gzip",
      "originalSize": 8421134,
      "finalSize": 6234421,
      "downloadUrl": "data:application/gzip;base64,..."
    }
  ]
}

​
Extract and convert a ZIP

When a ZIP is uploaded and the output format is not an archive, Convertly extracts supported files inside the ZIP and processes them individually. 
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./product-images.zip" \
  -F "format=webp" \
  -F "resize=ecommerce" \
  -F "compression=84"

​
Async archive delivery

Use async jobs for larger archives or delivery bundles. Jobs are storage-backed so workers can process the source files safely. 
curl -X POST "https://convertly.sh/api/jobs" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Idempotency-Key: agency-delivery-42" \
  -F "jobType=convert" \
  -F "saveToStorage=true" \
  -F "createArchive=true" \
  -F "files=@./delivery.zip" \
  -F 'formats=["webp"]' \
  -F 'compressions=[82]' \
  -F 'resizes=["website"]'

{
  "jobId": "65f3a673-69d6-42cc-8f6b-fc5a21fb5a8e",
  "status": "pending"
}
Poll GET /api/jobs/{id} or listen for webhooks to retrieve the completed files and archive output.

​
Supported archive outputs

zip, tar, tgz, 7z, rar, gz, bz2, and xz. Single-file compression formats such as gz, bz2, and xz are best for one source file. Use zip, tar, tgz, or 7z for grouped output bundles.