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

# Archive API

> Convert, extract, and package archive files with Convertly.

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

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

```json theme={"system"}
{
  "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.

```bash theme={"system"}
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.

```bash theme={"system"}
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"]'
```

```json theme={"system"}
{
  "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.

```bash theme={"system"}
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"
  }'
```

| 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

```bash theme={"system"}
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
  }'
```

```json theme={"system"}
{
  "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
  }
}
```

| 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

```bash theme={"system"}
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

```bash theme={"system"}
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 }'
```

```bash theme={"system"}
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.