---
title: "createZipJob"
method: POST
path: "/v1/files:zipJob"
tags: ["File"]
---

# createZipJob

`POST /v1/files:zipJob`

Create a background job to ZIP multiple files and send a download link via email.

For bulk downloads of more than 50 files, use this async endpoint instead of client-side zipping.
The job will:
1. Download all requested files from S3
2. Create a ZIP archive
3. Upload the ZIP to temporary storage
4. Send an email notification with the download link

The ZIP file will be available for 7 days.

## Request body

- union — Request payload to create a ZIP job for bulk file download. Provide either an explicit list of `file_entity_ids` (up to 1000) or an `entity_query` that resolves to file entities (up to 10000).
  - object
    - `file_entity_ids` string[], required — List of file entity IDs to include in the ZIP
    - `entity_query` object — Entity search query used to resolve files to include in the ZIP
      - `q` string, required — Lucene-style search query (same syntax as entity search)
      - `sort` string — Sort expression forwarded to the entity search
    - `zip_filename` string — Name of the generated ZIP file
    - `notify_email` string, email — Email address to notify when the ZIP is ready. Omit to skip the email notification.
  - object
    - `file_entity_ids` string[] — List of file entity IDs to include in the ZIP
    - `entity_query` object, required — Entity search query used to resolve files to include in the ZIP
      - `q` string, required — Lucene-style search query (same syntax as entity search)
      - `sort` string — Sort expression forwarded to the entity search
    - `zip_filename` string — Name of the generated ZIP file
    - `notify_email` string, email — Email address to notify when the ZIP is ready. Omit to skip the email notification.

## Response `202`

Job created, processing in background

- ZipJob — ZIP job status and result
  - `job_id` string, uuid — Unique identifier for the ZIP job
  - `status` 'queued' | 'downloading' | 'zipping' | 'uploading' | 'sending_notification' | 'completed' | 'failed' — Current status of the ZIP job
  - `progress` object — Progress information for the job
    - `total_files` integer — Total number of files to process
    - `downloaded_files` integer — Number of files successfully downloaded
    - `failed_files` integer — Number of files that failed to download
  - `result` object — Result of the completed ZIP job
    - `file_entity_id` string, uuid — File entity ID of the generated ZIP
    - `download_url` string, uri — Presigned download URL (expires in 24 hours)
    - `expires_at` string, date-time — When the download URL expires
    - `zip_size_bytes` integer — Size of the generated ZIP file in bytes
  - `error` string — Error message if job failed
  - `created_at` string, date-time — When the job was created
  - `created_by` string — User ID who created the job
  - `org_id` string — Organization ID
  - `updated_at` string, date-time — When the job was last updated

## Other responses

- `400` — Invalid request parameters or payload
- `401` — Authentication required or invalid credentials
- `500` — An unexpected error occurred on the server

---

[API](https://skmtc.net/epilot/apis/file-api.md) · [All operations](https://skmtc.net/epilot/apis/file-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/file-api/revisions/4d61b97f1e97/schema)