> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zipkit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Zips

> Understanding zip creation and lifecycle in ZipKit

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

<Steps>
  <Step title="none">
    Initial state when the zip is first created. The job is queued but hasn't started processing yet.
  </Step>

  <Step title="processing">
    ZipKit is actively downloading files and creating the zip archive. This is where most of the work happens.
  </Step>

  <Step title="succeeded">
    The zip was successfully created and uploaded to your bucket. The file is ready to use.
  </Step>

  <Step title="failed">
    Something went wrong during processing. Common causes include inaccessible URLs or bucket permission issues.
  </Step>
</Steps>

## 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`)

```bash theme={null}
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:**

```json theme={null}
{
  "data": {
    "uuid": "clx7g2m4p0000xyz123abc",
    "status": "none"
  }
}
```

## Tracking Progress

Configure a webhook URL in your project settings to receive automatic notifications when zips complete:

```json theme={null}
{
  "type": "COMPLETED",
  "zip_id": "clx7g2m4p0000xyz123abc",
  "status": "succeeded",
  "bucket": {
    "service": "s3",
    "name": "my-bucket"
  },
  "key": "my-archive.zip"
}
```

See [Webhooks](/guides/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:**

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

```bash theme={null}
{
  "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):

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

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