Archive API

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

Task	How it works
Convert archive formats	Send an archive to `POST /api/convert` and choose an archive output such as `zip`, `tar`, `tgz`, `7z`, `gz`, `bz2`, or `xz`.
Process files inside ZIPs	Upload a ZIP and choose a non-archive output format to extract supported files and convert them as a batch.
Package generated files	Use `createArchive=true` on async jobs when your app wants one grouped download for the completed outputs.
Download saved files as an archive	In the dashboard file manager, users can archive selected stored files or folders.
Schedule recurring folder snapshots	Per-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": "e7a3c9d2-4f18-4b65-9a2e-73d8c1f056ab",
    "format": "zip",
    "recursive": true,
    "delivery": "library"
  }'

Field	Purpose
`folderId`	Folder to archive (`null` for root-level selection with `fileIds`)
`fileIds`	Optional explicit file list instead of a whole folder
`format`	`zip`, `tar`, or `tgz`
`delivery`	`library` 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": "e7a3c9d2-4f18-4b65-9a2e-73d8c1f056ab",
    "name": "Client delivery backup",
    "frequency": "daily",
    "hour": 2,
    "minute": 0,
    "timezone": "America/New_York",
    "format": "zip",
    "retentionCount": 7,
    "retentionDays": 90
  }'

{
  "schedule": {
    "id": "b42d8e61-7c3a-4f90-a5d2-8e19c64b07f3",
    "folderId": "e7a3c9d2-4f18-4b65-9a2e-73d8c1f056ab",
    "name": "Client delivery backup",
    "enabled": true,
    "nextRunAt": "2026-06-22T06:00:00.000Z",
    "retentionCount": 7,
    "retentionDays": 90
  }
}

Field	Purpose
`folderId`	Required. The folder to snapshot. One schedule applies to one folder.
`name`	Human-readable label for the schedule
`frequency`	`daily`, `weekly`, or `monthly`
`hour`, `minute`	Run time in the schedule timezone
`dayOfWeek`	For `weekly` schedules. `0` = Sunday through `6` = Saturday
`dayOfMonth`	For `monthly` schedules. `1`–`28`
`timezone`	IANA timezone, e.g. `UTC`, `Europe/London`, `America/Los_Angeles`
`targetFolderId`	Optional 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.
`retentionCount`	Keep at most this many snapshots (default `7`)
`retentionDays`	Delete snapshots older than this many days (default `90`)
`enabled`	Pause or resume without deleting the schedule

List schedules

curl "https://convertly.sh/api/folder-archive-schedules?folderId=e7a3c9d2-4f18-4b65-9a2e-73d8c1f056ab" \
  -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/b42d8e61-7c3a-4f90-a5d2-8e19c64b07f3" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

curl -X DELETE "https://convertly.sh/api/folder-archive-schedules/b42d8e61-7c3a-4f90-a5d2-8e19c64b07f3" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

How scheduled snapshots run

When a schedule is due, Convertly:

Creates an idempotent run record
Starts the same async archive job used by POST /api/files/archive
Saves the archive to your library with schedule metadata (archive_schedule_id, archive_is_scheduled)
Applies retention — removes older snapshots beyond your count/day limits
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.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

What archive handling does

Archive conversion

Extract and convert a ZIP

Async archive delivery

Folder archive jobs (storage)

Scheduled folder snapshots

Create a schedule

List schedules

Update or delete

How scheduled snapshots run

Outsource on your own cron (optional)

Supported archive outputs

​What archive handling does

​Archive conversion

​Extract and convert a ZIP

​Async archive delivery

​Folder archive jobs (storage)

​Scheduled folder snapshots

​Create a schedule

​List schedules

​Update or delete

​How scheduled snapshots run

​Outsource on your own cron (optional)

​Supported archive outputs

What archive handling does

Archive conversion

Extract and convert a ZIP

Async archive delivery

Folder archive jobs (storage)

Scheduled folder snapshots

Create a schedule

List schedules

Update or delete

How scheduled snapshots run

Outsource on your own cron (optional)

Supported archive outputs