Skip to main content

​
Overview

Zips are the core of ZipKit - they represent jobs that fetch files from remote URLs, bundle them into a zip archive, and store the result in your cloud storage bucket.

​
How Zip Creation Works

When you create a zip, ZipKit performs these steps asynchronously:
  1. Validates your request (bucket exists, URLs are valid)
  2. Downloads each file from the provided URLs
  3. Creates a zip archive containing all downloaded files
  4. Uploads the zip to your configured cloud storage bucket
  5. Sends a webhook notification (if configured)
The entire process is asynchronous - the API returns immediately with a zip ID, and processing happens in the background.

​
Zip Lifecycle

A zip job progresses through these statuses:
1

none

Initial state when the zip is first created. The job is queued but hasn’t started processing yet.
2

processing

ZipKit is actively downloading files and creating the zip archive. This is where most of the work happens.
3

succeeded

The zip was successfully created and uploaded to your bucket. The file is ready to use.
4

failed

Something went wrong during processing. Common causes include inaccessible URLs or bucket permission issues.

​
Creating a Zip

Create a zip via the API by providing:
  • urls: Array of file objects, each with url and filename
  • bucket_name: Name of the configured bucket to store the zip
  • key: Filename/path for the zip in your bucket
  • service (optional): s3 or r2 (defaults to s3)
curl -X POST https://api.zipkit.io/v1/zips \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      {
        "url": "https://app.zipkit.io/onboarding/success.jpg",
        "filename": "success.jpg"
      },
      {
        "url": "https://app.zipkit.io/onboarding/welcome.txt",
        "filename": "welcome.txt"
      }
    ],
    "bucket_name": "my-bucket",
    "key": "example.zip"
  }'
Response: 
{
  "data": {
    "uuid": "clx7g2m4p0000xyz123abc",
    "status": "none"
  }
}

​
Tracking Progress

Configure a webhook URL in your project settings to receive automatic notifications when zips complete: 
{
  "type": "COMPLETED",
  "zip_id": "clx7g2m4p0000xyz123abc",
  "status": "succeeded",
  "bucket": {
    "service": "s3",
    "name": "my-bucket"
  },
  "key": "my-archive.zip"
}
See Webhooks for complete webhook documentation.

​
Where Zips are Stored

When a zip completes successfully, it’s stored in your configured cloud storage bucket at the key you specified. Example: If you set "key": "my-archive.zip", the zip is stored at: 
my-bucket/my-archive.zip
You can then access the zip file using your cloud provider’s SDK, console, or direct URL.

​
File Naming Inside Zips

Files inside the zip archive use the filenames you specify in the urls array. Each file object requires both a url (where to fetch the file) and a filename (what to name it in the zip). Example: 
{
  "url": "https://example.com/documents/abc123.pdf",
  "filename": "monthly-report.pdf"
}
This gives you full control over how files are named in the resulting zip archive.

​
Common Patterns

​
One-Time Archives

Create a zip once for a specific set of files: 
{
  "urls": [
    {
      "url": "https://example.com/invoice.pdf",
      "filename": "invoice-12345.pdf"
    }
  ],
  "bucket_name": "invoices",
  "key": "invoice-12345.zip"
}

​
Recurring Archives

Create zips on a schedule (e.g., daily reports): 
{
  "urls": [
    {
      "url": "https://example.com/reports/daily-2025-11-16.csv",
      "filename": "daily-report.csv"
    }
  ],
  "bucket_name": "reports",
  "key": "reports/daily-2025-11-16.zip"
}

​
Dynamic Content

Fetch the latest files from a content system and bundle them: 
{
  "urls": [
    {
      "url": "https://cms.example.com/latest/article.html",
      "filename": "article.html"
    },
    {
      "url": "https://cms.example.com/latest/images/header.jpg",
      "filename": "header.jpg"
    }
  ],
  "bucket_name": "archives",
  "key": "content/latest.zip"
}

​
Managing Zips

​
Viewing Zips

View all zip jobs for a project in the dashboard. The zip list shows:
  • zip ID
  • Status
  • Creation date
  • Bucket used

​
Failed Zips

If a zip fails, common causes include:
  • Inaccessible URLs: Source files returned 404 or other errors
  • Network issues: Timeouts or connection failures
  • Bucket permissions: Insufficient permissions to write to the bucket
  • Invalid bucket: Bucket doesn’t exist or was deleted
Check the status and retry with corrected parameters if needed.