Archive workflows - Convertly Developer Documentation

Use archive workflows when your users upload folders, grouped product assets, client delivery packages, or exported media sets.

Use POST /api/convert with createArchive=true to bundle outputs, POST /api/files/archive for one-off storage archives, or POST /api/folder-archive-schedules for managed per-folder snapshot schedules.

Choose the right flow

Flow	Endpoint
Convert one archive format to another	`POST /api/convert`
Extract a ZIP and convert supported files inside	`POST /api/convert`
Process a large archive in the background	`POST /api/jobs`
Return one archive for a completed batch	`POST /api/jobs` with `createArchive=true`
Archive a folder already in Convertly Storage	`POST /api/files/archive`
Recurring per-folder snapshots with retention	`POST /api/folder-archive-schedules`

Convert an archive

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

Process a ZIP as a batch

curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./images.zip" \
  -F "format=webp" \
  -F "resize=website" \
  -F "compression=82"

Queue a larger archive

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

Async archive jobs return a jobId. Poll GET /api/jobs/{id} or subscribe to webhooks for completion.

Schedule per-folder snapshots

Create one schedule per folder when you want Convertly to run backups automatically:

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": "Weekly client backup",
    "frequency": "weekly",
    "dayOfWeek": 0,
    "hour": 3,
    "minute": 0,
    "timezone": "UTC",
    "retentionCount": 4,
    "retentionDays": 180
  }'

List schedules for a folder with GET /api/folder-archive-schedules?folderId={uuid}. See the Archive API reference for retention, pause/resume, and delete.

Last modified on July 17, 2026