API Reference
Create Zip
Create a new zip archive from remote files
POST
Overview
The Create Zip endpoint accepts a list of URLs pointing to remote files, downloads them, bundles them into a zip archive, and uploads the result to your configured cloud storage bucket. Zip creation is asynchronous - the endpoint returns immediately with a job ID, and the actual processing happens in the background.Endpoint
Authentication
Requires a valid access token in theAuthorization header:
Request Body
An array of file objects to include in the zip archive. Each object specifies a URL to fetch and the desired filename in the zip.Structure: Each object must contain:
url(string, required): URL to fetch the file from. Must be publicly accessible.filename(string, required): Desired filename for this file in the zip archive.
- At least 1 file object required
- Files will be included in the zip in the order provided
The name of the S3 or R2 bucket where the zip archive will be stored. This must match a bucket you’ve configured in your project settings.
The filename for the zip archive in your bucket.Example:
"reports/monthly-report-2025-11.zip"The cloud storage service to use. Defaults to
"s3" if not specified.Options:"s3"- AWS S3 (default)"r2"- Cloudflare R2
Custom metadata to attach to this zip. Accepts any valid JSON object. This metadata will be:
- Stored with the zip in the database
- Returned in all API responses (POST and GET)
- Included in webhook payloads when the zip completes
- Track internal references (user IDs, order IDs, etc.)
- Store custom identifiers for your application
- Pass through contextual information to webhook handlers
The response data object containing zip information.
Unique identifier (UUID) for this zip job. Use this to retrieve the zip status via GET /api/v1/zips/:id.
Current status of the zip job. Will be
"none" when first created.Possible values:none- Job created, not yet started processingprocessing- Currently downloading files and creating zipsucceeded- zip successfully created and uploaded to your bucketfailed- Job failed during processing
The custom metadata object provided in the request. Returns the exact metadata you sent, or an empty object
{} if none was provided.Zip Creation Process
After you create a zip job, ZipKit performs these steps asynchronously:- Validates the bucket ID and URLs
- Downloads each file from the provided URLs
- Creates a zip archive containing all downloaded files
- Uploads the zip to your configured cloud storage bucket
- Sends a webhook notification (if configured)
- Number of files
- Size of files
- Network speed when downloading from source URLs
- Upload speed to your cloud storage
Checking Status
The Create Zip endpoint returns immediately - it doesn’t wait for the zip to be created. To check the status: Use webhooks (recommended): Configure a webhook to receive automatic notifications when the zip completesError Responses
All errors follow a consistent JSON format:401 Unauthorized
Returned when authentication fails.Missing Authorization Header
Invalid API Key
Authorization header.
404 Not Found
Returned when the specified bucket doesn’t exist or doesn’t belong to your project. Solution: Verify thebucket_name matches a bucket you’ve configured in your project.
422 Unprocessable Entity
Returned when a required parameter is missing or invalid.Missing Required Parameter
- Missing
bucket_name,key, orurlsparameter
Invalid Parameter
urlsis not an array or is empty- Invalid URL format
- Invalid data types
Best Practices
Validate URLs before sending
Validate URLs before sending
Make sure all URLs are accessible and return the expected files. ZipKit will attempt to download from each URL - if a URL is inaccessible, the zip job may fail.
Use descriptive keys
Use descriptive keys
Specify a meaningful
key parameter to organize your zips in your bucket (e.g., "reports/monthly-2025-11.zip" instead of letting ZipKit auto-generate one).Consider file sizes
Consider file sizes
Very large files or many files can take longer to process. Use webhooks to track completion.
Use descriptive filenames
Use descriptive filenames
Provide clear, descriptive filenames for each file in the zip (e.g.,
monthly-report-2025-11.pdf instead of file.pdf). This makes the zip contents easier to understand for end users.Configure buckets properly
Configure buckets properly
Ensure your destination bucket exists and has proper write permissions for the credentials configured in your project.
Zip File Location
When the zip is complete, it will be stored in your specified bucket at thekey you provided.
Example:
If you set "key": "reports/monthly-2025-11.zip", the zip will be stored at:
Limits and Quotas
Rate Limits: API rate limits may apply depending on your plan. Contact support for details on your specific limits.