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

# Buckets

> Configure cloud storage buckets for your zip archives

## Overview

Buckets are cloud storage destinations where ZipKit stores your zip archives. Before you can create zips, you need to configure at least one bucket in your project.

ZipKit supports:

* **AWS S3** - Amazon's Simple Storage Service
* **Cloudflare R2** - Cloudflare's S3-compatible object storage

<Note>
  **Why bucket credentials are required:** ZipKit streams zip archives directly to your bucket using multipart uploads. A presigned URL cannot be used since they don't support the multipart upload operations needed for efficient streaming.
</Note>

## Configuring a Bucket

Buckets are configured through the ZipKit dashboard, not via API. Here's how:

### Step 1: Navigate to Buckets

1. Log in to your ZipKit dashboard
2. Select your project
3. Go to the "Buckets" section
4. Click "Add Bucket"

### Step 2: Choose Your Provider

Select either **AWS S3** or **Cloudflare R2** based on where you want to store your zips.

<Tabs>
  <Tab title="AWS S3">
    ### Required Information

    <ParamField body="Bucket Name" type="string" required>
      The name of your existing S3 bucket (e.g., `my-zipkit-archives`)

      **Note:** The bucket must already exist in your AWS account. ZipKit won't create it for you.
    </ParamField>

    <ParamField body="Access Key ID" type="string" required>
      Your AWS IAM access key ID (e.g., `AKIAIOSFODNN7EXAMPLE`)

      **Security tip:** Create a dedicated IAM user for ZipKit with limited permissions (see below).
    </ParamField>

    <ParamField body="Secret Access Key" type="string" required>
      Your AWS IAM secret access key

      **Note:** This is stored securely and encrypted. You won't be able to view it after initial setup.
    </ParamField>

    <ParamField body="Region" type="string" required>
      The AWS region where your bucket is located (e.g., `us-east-1`, `eu-west-1`)

      **Note:** Required to connect to the correct S3 endpoint for your bucket.
    </ParamField>

    ### Required IAM Permissions

    The IAM user must have permission to write to your bucket. Here's a minimal IAM policy:

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:PutObject",
            "s3:PutObjectAcl"
          ],
          "Resource": "arn:aws:s3:::your-bucket-name/*"
        }
      ]
    }
    ```

    **Security best practice:** Create a dedicated IAM user specifically for ZipKit with only these permissions.
  </Tab>

  <Tab title="Cloudflare R2">
    ### Required Information

    <ParamField body="Bucket Name" type="string" required>
      The name of your existing R2 bucket (e.g., `my-zipkit-archives`)

      **Note:** The bucket must already exist in your Cloudflare account.
    </ParamField>

    <ParamField body="Host" type="string" required>
      The R2 endpoint for your account (e.g., `abc123.r2.cloudflarestorage.com`)

      **Format:** `<account-id>.r2.cloudflarestorage.com`

      Replace `<account-id>` with your Cloudflare account ID.
    </ParamField>

    <ParamField body="Access Key ID" type="string" required>
      Your R2 access key ID

      You can create API tokens in the Cloudflare dashboard under R2 > Manage R2 API Tokens.
    </ParamField>

    <ParamField body="Secret Access Key" type="string" required>
      Your R2 secret access key

      **Note:** This is stored securely and encrypted.
    </ParamField>

    <ParamField body="Account ID" type="string" required>
      Your Cloudflare account ID

      You can find this in your Cloudflare dashboard URL or in the R2 section.
    </ParamField>

    ### Creating an R2 Bucket

    If you don't have an R2 bucket yet:

    1. Go to the [Cloudflare Dashboard](https://dash.cloudflare.com/)
    2. Navigate to R2
    3. Click "Create bucket"
    4. Choose a bucket name
    5. Create the bucket
    6. Go to "Manage R2 API Tokens"
    7. Create a new API token with "Object Read & Write" permissions for your bucket
    8. Save the Access Key ID and Secret Access Key for ZipKit configuration

    ### R2 Advantages

    * **No egress fees** - Free data transfer out
    * **S3-compatible API** - Works with existing S3 tools
    * **Competitive pricing** - Often cheaper than S3
  </Tab>
</Tabs>

### Step 3: Save and Test

1. Enter all required information
2. Click "Save" or "Create Bucket"
3. If successful, your bucket will appear in the list

## Using Buckets in API Calls

When creating a zip via the API, reference your bucket by its **name**:

```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://example.com/file.pdf",
        "filename": "document.pdf"
      }
    ],
    "bucket_name": "my-zipkit-archives",
    "key": "document.zip"
  }'
```

The `bucket_name` must match a bucket you've configured in your project settings.

## Managing Buckets

### Viewing Buckets

All configured buckets are listed in your project's "Buckets" section. You can see:

* Bucket name
* Service (S3 or R2)
* Creation date
* Region (if applicable)

**Security:** The access keys are never displayed after initial creation.

### Editing Buckets

To update bucket credentials:

1. Go to the "Buckets" section
2. Click "Edit" next to the bucket
3. Update the credentials
4. Save changes

### Deleting Buckets

To remove a bucket configuration:

1. Go to the "Buckets" section
2. Click "Delete" next to the bucket
3. Confirm deletion

<Warning>
  **Warning:** You cannot delete a bucket if there are existing zip jobs associated with it. The zip jobs will fail if you delete the bucket configuration.
</Warning>

## Multiple Buckets

You can configure multiple buckets in a single project:

**Use cases:**

* Separate buckets for different types of archives
* Geographic distribution (buckets in different regions)
* Cost optimization (use R2 for some zips, S3 for others)

When creating a zip, specify which bucket to use with the `bucket_name` parameter.