How to Start a Zip Job with the S3zipper API

The zipstart endpoint creates a zip job and returns immediately: the archive is built in the background, and you poll for the result. This is the right way to zip large or many files without holding a request open.

The request

curl -X POST https://api.s3zipper.com/v1/zipstart \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "awsKey": "AKIA...",
    "awsSecret": "...",
    "awsBucket": "my-bucket",
    "awsRegion": "us-east-1",
    "filePaths": ["my-bucket/reports/2026", "my-bucket/summary.pdf"],
    "zipFileName": "reports.zip"
  }'

Request fields

awsKey, awsSecret — credentials that may read the bucket (and write the archive). Add awsToken for temporary STS credentials.
awsBucket, awsRegion — where the files live.
filePaths — full S3 keys: files, folders, or both. Folders are expanded recursively.
zipFileName — the name of the downloaded archive.
expireLink — how long the download URL stays valid, in hours (default 168, i.e. seven days).
resultsEmail — optional; send the download link to that address when the job finishes.

The response

{
  "message": "STARTED",
  "size": "181 MB",
  "taskUUID": [{"streams3v2": "9f2c1e7a-..."}],
  "jobID": "9f2c1e7a-...",
  "status": "created"
}

size is the total of the resolved files. The taskUUID is what you send to the state and result endpoints — or keep the whole response and replay it.

Background jobs and limits

The job runs outside your request. Plan limits apply to the total size of the archive: the free plan allows 10 MB per request, paid plans allow much more. If a request is rejected you will see a clear message rather than a silent failure.

Need it even faster?

/v1/zipstartid returns the task id without pre-processing the files — useful for very fast responses. Validation, limits and the zip itself then happen in the background. Next: check the task status.