> ## Documentation Index
> Fetch the complete documentation index at: https://bunnynet-cb9733c2-support-migration.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# S3

Bunny Storage supports an S3-compatible API (currently in beta), allowing you to use familiar S3 tools, libraries, and workflows with your storage zones. Use existing S3 tools and scripts, leverage popular S3 libraries across all programming languages, migrate from AWS S3 with minimal code changes, and work with S3 GUI tools.

<Info>
  S3 compatibility is currently in closed preview. S3 compatibility must be enabled during storage zone creation and cannot be changed afterward.
</Info>

## Creating a storage zone with S3 compatibility

To create an S3-compatible storage zone:

1. Navigate to **Storage** → **Add Storage Zone**
2. Enter a name (minimum 4 characters, letters, numbers, and dashes only)
3. Enable the **S3 Compatibility** option
4. Select your preferred storage tier
5. Choose your region
6. Configure replication
7. Confirm and **Add Storage Zone**

## Quickstart

Once you've created your S3-compatible storage zone, you're ready to connect.

### Authentication and credentials

The credentials you need to connect via S3 are located in the **Access** tab:

* **Access Key ID**: Your Storage Zone name (bucket name)
* **Secret Access Key**: Your Storage Zone Password
* **Endpoint URL**: `https://[region]-s3.storage.bunnycdn.com`
* **Region**: `de` (Frankfurt), `ny` (New York), `sg` (Singapore), `uk` (London), `se` (Stockholm), `la` (Los angeles) or `jh` (Johannesburg)

<Note>
  Bunny Storage only supports path-style URLs (e.g., `https://[region]-s3.storage.bunnycdn.com/bucket-name/key`). Virtual hosted-style URLs (e.g., `bucket-name.s3.region.amazonaws.com`) are not supported.
</Note>

### Content Type Detection

When uploading objects, Content-Type is determined in the following order:

1. **Content-Type header** - If provided in the request
2. **File extension detection** - Automatic detection based on file extension
3. **Default fallback** - `binary/octet-stream` for unknown types

### Checksum Validation

SHA256 checksum validation is available using the `x-amz-checksum-sha256` header (Base64 encoded).\\

### Presigned URL Validation

Presigned URLs require authentication. For publicly available presigned URLs without authentication please use [bunny.net](http://bunny.net) CDN by adding a pullzone to your storage zone.

| Parameter             | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `X-Amz-Algorithm`     | Signing algorithm type (AWS4-HMAC-SHA256)                    |
| `X-Amz-Credential`    | Access key + date + region + service + aws4\_request         |
| `X-Amz-Date`          | Timestamp URL signed in 'YYYYMMDDTHHMMSSZ' format            |
| `X-Amz-Expires`       | Validity duration in seconds from X-Amz-Date (default 1hour) |
| `X-Amz-SignedHeaders` | Headers included in the signature                            |
| `X-Amz-Signature`     | The HMAC-SHA256 signature                                    |

**Presigned URL example (1hour):**\
https\://\[region]-s3.storage.bunnycdn.com/bucket-name/path/to/object/?X-Amz-Algorithm=AWS4-HMAC-SHA256\&X-Amz-Credential=\[AccessKeyID+Date+region+servicerequest]\&X-Amz-Date=20260320T160912Z\&X-Amz-Expires=3600\&X-Amz-SignedHeaders=host\&X-Amz-Signature=\[HMAC-SHA256Signature]/

## Examples

### AWS CLI

<Note>
  You must use `--endpoint-url https://[region]-s3.storage.bunnycdn.com` with each command or set up an [AWS CLI profile](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-configure-files-methods) with the endpoint configured.
</Note>

```bash theme={null}
# Configure AWS CLI with your storage zone credentials
aws configure --profile bunny
# AWS Access Key ID: your-storage-zone-name
# AWS Secret Access Key: your-storage-password
# Default region name: your-region (e.g., de, ny, sg)
# Default output format: json

# Upload an object (PUT Object)
aws s3 cp /path/to/local/file s3://bucket-name/path/to/destination/ \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com

# Download an object (GET Object)
aws s3 cp s3://bucket-name/path/to/object /path/to/local/destination/ \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com

# List objects (LIST Objects)
aws s3 ls s3://bucket-name/ --recursive \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com

# Delete an object (DELETE Object)
aws s3 rm s3://bucket-name/path/to/object \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com

# Copy object (COPY Object)
aws s3 cp s3://bucket-name/source/object s3://bucket-name/destination/object \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com

# Get object metadata (HEAD Object)
aws s3api head-object --bucket bucket-name --key path/to/object \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com

# Sync a directory
aws s3 sync ./local-dir s3://bucket-name/remote-dir/ \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com

# Generate a pre-signed URL
aws s3 presign s3://bucket-name/path/to/object \
  --profile bunny \
  --endpoint-url https://[region]-s3.storage.bunnycdn.com 
  --expires-in 86400
```

### rclone

You can use rclone with Bunny Storage:

```bash theme={null}
# Configure rclone
rclone config create bunnycdn s3 \
  provider=Other \
  access_key_id=your-storage-zone-name \
  secret_access_key=your-storage-password \
  endpoint=https://[region]-s3.storage.bunnycdn.com

# Upload an object (PUT Object)
rclone copy /path/to/local/file bunnycdn:bucket-name/path/to/destination/

# Download an object (GET Object)
rclone copy bunnycdn:bucket-name/path/to/object /path/to/local/destination/

# List objects (LIST Objects)
rclone ls bunnycdn:bucket-name/
rclone lsd bunnycdn:bucket-name/  # List directories only
rclone lsl bunnycdn:bucket-name/  # List with size and modification time

# Delete an object (DELETE Object)
rclone delete bunnycdn:bucket-name/path/to/object

# Delete a directory
rclone purge bunnycdn:bucket-name/path/to/directory/

# Copy object within bucket (COPY Object)
rclone copy bunnycdn:bucket-name/source/object bunnycdn:bucket-name/destination/

# Get object info (HEAD Object)
rclone lsl bunnycdn:bucket-name/path/to/object

# Sync a directory
rclone sync ./local-dir bunnycdn:bucket-name/remote-dir/

# Move objects
rclone move /path/to/local/file bunnycdn:bucket-name/destination/

# Copy object from URL
rclone copyurl URL bunnycdn:bucket-name/destination/
```

## Supported S3 operations

Bunny Storage provides comprehensive S3 API compatibility for all your storage needs.

### Object operations

* **PUT Object**: Create and update objects
* **GET Object**: Read objects (range requests supported)
* **DELETE Object**: Delete objects (single and batch operations)
* **COPY Object**: Copy objects between locations
* **HEAD Object**: Get object metadata
* **PRESIGN Object**: Generate object URL expiry time (Set in seconds - default 1 hour)

### Directory listing

* **LIST Objects**: List objects (V1 and V2)
* List with prefix filtering
* Paginated results
* Directory-style navigation
* Common prefixes support

### Multipart upload operations

Bunny Storage provides full support for S3 multipart uploads, enabling efficient upload of large objects. Recommended for objects over 100MB.

| API Name                                                                                                        | Features                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅ [`CreateMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html)     | ✅ Multipart session creation<br />✅ Returns UploadId<br />✅ System Metadata:<br />    ✅ Content-Type (with automatic detection from file extension)<br />    ✅ Content-Type stored in session for final object<br />✅ Automatic replication session creation<br />❌ Storage class selection<br />❌ Cache-Control, Content-Disposition, etc.<br />❌ SSE/SSE-C encryption<br />❌ Object tagging<br />❌ Object locking<br />❌ ACL headers |
| ✅ [`UploadPart`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html)                           | ✅ Part upload (up to 10,000 parts)<br />✅ Returns ETag (part checksum)<br />✅ Automatic replication of parts<br />❌ Content-MD5 validation<br />❌ SSE/SSE-C encryption                                                                                                                                                                                                                                                                 |
| ✅ [`UploadPartCopy`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html)                   | ✅ Copy within same storage zone<br />✅ Part size up to 5 GB<br />✅ Range copy (source object must be greater than 5 MB)<br />✅ Supported headers:<br />    ✅ x-amz-copy-source<br />    ✅ x-amz-copy-source-range (optional, format: bytes=first-last)<br />❌ Cross-zone copying<br />❌ Conditional source headers<br />❌ Server-side encryption<br />❌ Bucket-owner verification<br />❌ Requester payer<br />❌ ACL grants             |
| ✅ [`ListParts`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html)                             | ✅ Query Parameters:<br />    ✅ max-parts (default 1000)<br />    ✅ part-number-marker<br />✅ Returns part ETag and size<br />✅ Pagination support<br />✅ IsTruncated flag                                                                                                                                                                                                                                                              |
| ✅ [`CompleteMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | ✅ Finalizes multipart upload<br />✅ Validates all parts present<br />✅ Validates part ETags<br />✅ Creates final object with combined checksum<br />✅ Final checksum format: `MD5(part1+part2+...)-{partCount}`<br />✅ Applies Content-Type from session<br />✅ Automatic replication of completed object<br />✅ Cleanup of part files<br />✅ Returns ETag, Location, Bucket, Key<br />❌ Checksums in response                         |
| ✅ [`AbortMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html)       | ✅ Cancels multipart upload<br />✅ Deletes all uploaded parts                                                                                                                                                                                                                                                                                                                                                                           |
| ✅ [`ListMultipartUploads`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html)       | ✅ Query Parameters:<br />    ✅ prefix<br />    ✅ delimiter<br />    ✅ key-marker<br />    ✅ upload-id-marker<br />    ✅ max-uploads (default 1000)<br />✅ Pagination support<br />✅ Returns UploadId, Key, Initiated date                                                                                                                                                                                                              |

### S3 API compatibility matrix

Below is a detailed list of implemented object-level operations with their supported features:

| API Name                                                                                    | Features                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅ [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)       | ✅ Basic metadata retrieval<br />✅ Response headers:<br />    ✅ Content-Type<br />    ✅ Content-Length<br />    ✅ Last-Modified<br />❌ ETag<br />❌ Conditional Operations:<br />    ❌ If-Match<br />    ❌ If-Modified-Since<br />    ❌ If-None-Match<br />    ❌ If-Unmodified-Since<br />❌ Range queries<br />❌ SSE-C encryption headers                                                                                                                                                                                                                                                                                                 |
| ✅ [`GetObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)         | ✅ Full object download<br />✅ Response headers:<br />    ✅ Content-Type<br />    ✅ Content-Length<br />✅ Range requests (byte ranges)<br />✅ Multipart object download<br />❌ Conditional Operations:<br />    ❌ If-Match<br />    ❌ If-Modified-Since<br />    ❌ If-None-Match<br />    ❌ If-Unmodified-Since<br />❌ SSE-C encryption<br />❌ Versioning support                                                                                                                                                                                                                                                                        |
| ✅ [`PutObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)         | ✅ Object upload<br />✅ System Metadata:<br />    ✅ Content-Type (with automatic detection)<br />    ✅ Content-Length<br />✅ Checksum validation:<br />    ✅ x-amz-checksum-sha256 (Base64 encoded)<br />✅ Automatic replication to configured zones<br />❌ Storage Class selection<br />❌ Additional headers:<br />    ❌ Cache-Control<br />    ❌ Content-Disposition<br />    ❌ Content-Encoding<br />    ❌ Expires<br />    ❌ Content-Language<br />❌ SSE encryption<br />❌ SSE-C encryption<br />❌ Object tagging:<br />    ❌ x-amz-tagging<br />❌ Object locking<br />❌ ACL headers:<br />    ❌ x-amz-acl<br />    ❌ x-amz-grant-\* |
| ✅ [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html)   | ✅ Single object deletion<br />❌ Multi-factor authentication<br />❌ Object Locking<br />❌ Request Payer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ✅ [`CopyObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)       | ✅ Object copy within same storage zone<br />✅ Object size up to 5 GB<br />✅ Response fields:<br />    ✅ LastModified<br />    ✅ ChecksumSHA256 (Base64 encoded)<br />✅ Source object checksum validation<br />❌ Content-Type preservation<br />❌ ETag in response<br />❌ Cross-zone copying<br />❌ Metadata directive:<br />    ❌ x-amz-metadata-directive<br />❌ Conditional copy operations<br />❌ Storage class selection<br />❌ SSE/SSE-C encryption<br />❌ Tagging                                                                                                                                                                 |
| ✅ [`ListObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)     | ✅ Query Parameters:<br />    ✅ delimiter<br />    ✅ encoding-type<br />    ✅ marker<br />    ✅ max-keys<br />    ✅ prefix<br />✅ Common prefix support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ✅ [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) | ✅ Query Parameters:<br />    ✅ prefix<br />    ✅ delimiter<br />    ✅ max-keys<br />    ✅ continuation-token<br />    ✅ start-after<br />✅ Common prefix support<br />❌ fetch-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ✅ `Presign`                                                                                 | ✅ Configuration:<br />    ✅ expires-in<br />    ✅ Signing algorithm AWS4-HMAC-SHA256                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### Unsupported operations

<Accordion title="View unsupported S3 operations">
  The following S3 operations are not currently supported:

  | API Name                                                                                              | Feature                            |
  | ----------------------------------------------------------------------------------------------------- | ---------------------------------- |
  | ❌ [GetObjectAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectAcl.html)               | ❌ ACLs not supported               |
  | ❌ [PutObjectAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectAcl.html)               | ❌ ACLs not supported               |
  | ❌ [GetObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectTagging.html)       | ❌ Object tagging not supported     |
  | ❌ [PutObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectTagging.html)       | ❌ Object tagging not supported     |
  | ❌ [DeleteObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjectTagging.html) | ❌ Object tagging not supported     |
  | ❌ [GetObjectAttributes](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectAttributes.html) | ❌ Not implemented                  |
  | ❌ [GetObjectLegalHold](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectLegalHold.html)   | ❌ Object locking not supported     |
  | ❌ [PutObjectLegalHold](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLegalHold.html)   | ❌ Object locking not supported     |
  | ❌ [GetObjectRetention](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectRetention.html)   | ❌ Object retention not supported   |
  | ❌ [PutObjectRetention](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectRetention.html)   | ❌ Object retention not supported   |
  | ❌ [SelectObjectContent](https://docs.aws.amazon.com/AmazonS3/latest/API/API_SelectObjectContent.html) | ❌ S3 Select not supported          |
  | ❌ [RestoreObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html)             | ❌ Glacier operations not supported |
  | ❌ [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html)             | ❌ Batch delete not supported       |
</Accordion>

## Limits

Be aware of the following limitations when using S3-compatible storage:

### Regional availability

S3-compatible storage zones support automatic multi-region replication. All operations including uploads, deletes, and multipart uploads are automatically replicated to your configured replication regions.

S3 compatibility is currently only available in the following regions:

* Frankfurt (DE)
* New York (NY)
* Singapore (SG)
* London (UK)
* Stockholm (SE)
* Los Angeles (LA)
* Johannesburg (JH)

Additional regions will be added in the future.

<Note>
  S3 compatibility cannot be changed after storage zone creation.
</Note>

### Known limitations

The following S3 features are limited by:

* **CORS Configuration**: Cross-Origin Resource Sharing settings (must be handled at the CDN level)
* **Versioning**: Object versioning is not supported
* **ACLs**: Access Control Lists are not supported
* **Server-Side Encryption**: SSE/SSE-C encryption is not currently supported
* **Object Tagging**: Object and bucket tagging is not supported
* **Lifecycle Policies**: Automatic lifecycle transitions are not supported
* **Conditional Requests**: If-Match, If-Modified-Since headers not yet supported for GET/HEAD
* **Multipart Limits**: Maximum 10,000 parts per upload
* **Multipart Session Expiry**: Sessions expire after 10 days
* **Presigned URLs**: Minimum time: 1 second | Maximum time: 7 days (604800 seconds)

## Error Codes

Bunny Storage returns standard S3 error codes:

<Note>
  Some error codes may differ from standard AWS S3 behavior. See the notes below for Bunny-specific details.
</Note>

| Error Code           | HTTP Status | Description                                                                    |
| -------------------- | ----------- | ------------------------------------------------------------------------------ |
| `NoSuchKey`          | 404         | The specified file, folder, or multipart upload does not exist                 |
| `InvalidSecurity`    | 403         | Signature validation failed (incorrect bucket name, access key, or secret key) |
| `InvalidRequest`     | 400         | Invalid request parameters or headers                                          |
| `InternalError`      | 500         | Internal server error                                                          |
| `ServiceUnavailable` | 503         | S3 compatibility is not enabled for this storage zone                          |

## Best Practices

1. [**Use an SDK**](https://docs.aws.amazon.com/AmazonS3/latest/API/sdk-general-information-section.html) to interact with the S3 api
2. **Enable Replication** for at least one additional region
3. **Implement retry logic** for transient failures
4. **Use multipart uploads** for objects larger than 100MB
5. **Include Content-Type headers** when uploading, or rely on automatic detection
6. **Handle pagination properly** when listing objects or parts (max 1000 per request)
7. **Monitor multipart sessions** and abort abandoned uploads to free storage
8. **Set presigned URL expiry time** in seconds `--expires-in 3600` = 1hour