Skip to main content
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.
Schedule recurring folder snapshotsPer-folder schedules via dashboard or POST /api/folder-archive-schedules.

​
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.

​
Folder archive jobs (storage)

Large folder archives in Convertly Storage run asynchronously so the API returns immediately while workers package files in the background. 
curl -X POST "https://convertly.sh/api/files/archive" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "11111111-1111-1111-1111-111111111111",
    "format": "zip",
    "recursive": true,
    "delivery": "library"
  }'
FieldPurpose
folderIdFolder to archive (null for root-level selection with fileIds)
fileIdsOptional explicit file list instead of a whole folder
formatzip, tar, or tgz
deliverylibrary saves the archive to storage; download returns a one-time download when complete
Poll GET /api/files/archive/{jobId} until the archive is ready. In the dashboard, Assets → Back up folder uses the same flow and saves completed snapshots to the Backups tab (/app/files?view=backups).

​
Scheduled folder snapshots

Each folder can have its own recurring snapshot schedule. Schedules are per folder — you can back up /client-a, /client-b, and /exports on different cadences, retention rules, and timezones. Convertly runs due schedules automatically. You can manage them from the dashboard (Folder menu → Schedule snapshots) or entirely through the API with your Convertly API key.

​
Create a schedule

curl -X POST "https://convertly.sh/api/folder-archive-schedules" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "11111111-1111-1111-1111-111111111111",
    "name": "Client delivery backup",
    "frequency": "daily",
    "hour": 2,
    "minute": 0,
    "timezone": "America/New_York",
    "format": "zip",
    "retentionCount": 7,
    "retentionDays": 90
  }'

{
  "schedule": {
    "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "folderId": "11111111-1111-1111-1111-111111111111",
    "name": "Client delivery backup",
    "enabled": true,
    "nextRunAt": "2026-06-22T06:00:00.000Z",
    "retentionCount": 7,
    "retentionDays": 90
  }
}
FieldPurpose
folderIdRequired. The folder to snapshot. One schedule applies to one folder.
nameHuman-readable label for the schedule
frequencydaily, weekly, or monthly
hour, minuteRun time in the schedule timezone
dayOfWeekFor weekly schedules. 0 = Sunday through 6 = Saturday
dayOfMonthFor monthly schedules. 1–28
timezoneIANA timezone, e.g. UTC, Europe/London, America/Los_Angeles
targetFolderIdOptional override for where the archive is stored. By default, library delivery saves snapshots to the workspace Backups bucket (mirroring the source folder), not inside the live Assets tree.
retentionCountKeep at most this many snapshots (default 7)
retentionDaysDelete snapshots older than this many days (default 90)
enabledPause or resume without deleting the schedule

​
List schedules

curl "https://convertly.sh/api/folder-archive-schedules?folderId=11111111-1111-1111-1111-111111111111" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
Omit folderId to list every schedule in the workspace.

​
Update or delete

curl -X PATCH "https://convertly.sh/api/folder-archive-schedules/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

curl -X DELETE "https://convertly.sh/api/folder-archive-schedules/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

​
How scheduled snapshots run

When a schedule is due, Convertly:
  1. Creates an idempotent run record
  2. Starts the same async archive job used by POST /api/files/archive
  3. Saves the archive to your library with schedule metadata (archive_schedule_id, archive_is_scheduled)
  4. Applies retention — removes older snapshots beyond your count/day limits
  5. Disables the schedule after five consecutive failures until you re-enable it
Scheduled snapshots appear in the dashboard Backups tab (Assets → Backups), grouped under their source folder.

​
Outsource on your own cron (optional)

If you prefer to trigger archives yourself instead of using Convertly schedules, call POST /api/files/archive from your own scheduler (GitHub Actions, cron, Zapier, etc.) on whatever cadence you want. That path is fully API-driven and does not require Convertly schedule rows. Use Convertly schedules when you want retention, run history, and managed execution. Use your own cron + /api/files/archive when you want full external control of timing and orchestration.

​
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.