S3 - bunny.net Documentation

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.

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

Creating a storage zone with S3 compatibility

To create an S3-compatible storage zone:

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

S3 compatibility is currently only supported in Frankfurt, New York, and Singapore. Additional regions will be added later.

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)

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.

Content Type Detection

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

Content-Type header - If provided in the request
File extension detection - Automatic detection based on file extension
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 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

You must use --endpoint-url https://[region]-s3.storage.bunnycdn.com with each command or set up an AWS CLI profile with the endpoint configured.

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

# 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`	✅ Multipart session creation ✅ Returns UploadId ✅ System Metadata: ✅ Content-Type (with automatic detection from file extension) ✅ Content-Type stored in session for final object ✅ Automatic replication session creation ❌ Storage class selection ❌ Cache-Control, Content-Disposition, etc. ❌ SSE/SSE-C encryption ❌ Object tagging ❌ Object locking ❌ ACL headers
✅ `UploadPart`	✅ Part upload (up to 10,000 parts) ✅ Returns ETag (part checksum) ✅ Automatic replication of parts ❌ Content-MD5 validation ❌ SSE/SSE-C encryption
✅ `UploadPartCopy`	✅ Copy within same storage zone ✅ Part size up to 5 GB ✅ Range copy (source object must be greater than 5 MB) ✅ Supported headers: ✅ x-amz-copy-source ✅ x-amz-copy-source-range (optional, format: bytes=first-last) ❌ Cross-zone copying ❌ Conditional source headers ❌ Server-side encryption ❌ Bucket-owner verification ❌ Requester payer ❌ ACL grants
✅ `ListParts`	✅ Query Parameters: ✅ max-parts (default 1000) ✅ part-number-marker ✅ Returns part ETag and size ✅ Pagination support ✅ IsTruncated flag
✅ `CompleteMultipartUpload`	✅ Finalizes multipart upload ✅ Validates all parts present ✅ Validates part ETags ✅ Creates final object with combined checksum ✅ Final checksum format: `MD5(part1+part2+...)-{partCount}` ✅ Applies Content-Type from session ✅ Automatic replication of completed object ✅ Cleanup of part files ✅ Returns ETag, Location, Bucket, Key ❌ Checksums in response
✅ `AbortMultipartUpload`	✅ Cancels multipart upload ✅ Deletes all uploaded parts
✅ `ListMultipartUploads`	✅ Query Parameters: ✅ prefix ✅ delimiter ✅ key-marker ✅ upload-id-marker ✅ max-uploads (default 1000) ✅ Pagination support ✅ 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`	✅ Basic metadata retrieval ✅ Response headers: ✅ Content-Type ✅ Content-Length ✅ Last-Modified ❌ ETag ❌ Conditional Operations: ❌ If-Match ❌ If-Modified-Since ❌ If-None-Match ❌ If-Unmodified-Since ❌ Range queries ❌ SSE-C encryption headers
✅ `GetObject`	✅ Full object download ✅ Response headers: ✅ Content-Type ✅ Content-Length ✅ Range requests (byte ranges) ✅ Multipart object download ❌ Conditional Operations: ❌ If-Match ❌ If-Modified-Since ❌ If-None-Match ❌ If-Unmodified-Since ❌ SSE-C encryption ❌ Versioning support
✅ `PutObject`	✅ Object upload ✅ System Metadata: ✅ Content-Type (with automatic detection) ✅ Content-Length ✅ Checksum validation: ✅ x-amz-checksum-sha256 (Base64 encoded) ✅ Automatic replication to configured zones ❌ Storage Class selection ❌ Additional headers: ❌ Cache-Control ❌ Content-Disposition ❌ Content-Encoding ❌ Expires ❌ Content-Language ❌ SSE encryption ❌ SSE-C encryption ❌ Object tagging: ❌ x-amz-tagging ❌ Object locking ❌ ACL headers: ❌ x-amz-acl ❌ x-amz-grant-*
✅ `DeleteObject`	✅ Single object deletion ❌ Multi-factor authentication ❌ Object Locking ❌ Request Payer
✅ `CopyObject`	✅ Object copy within same storage zone ✅ Object size up to 5 GB ✅ Response fields: ✅ LastModified ✅ ChecksumSHA256 (Base64 encoded) ✅ Source object checksum validation ❌ Content-Type preservation ❌ ETag in response ❌ Cross-zone copying ❌ Metadata directive: ❌ x-amz-metadata-directive ❌ Conditional copy operations ❌ Storage class selection ❌ SSE/SSE-C encryption ❌ Tagging
✅ `ListObjects`	✅ Query Parameters: ✅ delimiter ✅ encoding-type ✅ marker ✅ max-keys ✅ prefix ✅ Common prefix support
✅ `ListObjectsV2`	✅ Query Parameters: ✅ prefix ✅ delimiter ✅ max-keys ✅ continuation-token ✅ start-after ✅ Common prefix support ❌ fetch-owner
✅ `Presign`	✅ Configuration: ✅ expires-in ✅ Signing algorithm AWS4-HMAC-SHA256

Unsupported operations

View unsupported S3 operations

The following S3 operations are not currently supported:

API Name	Feature
❌ GetObjectAcl	❌ ACLs not supported
❌ PutObjectAcl	❌ ACLs not supported
❌ GetObjectTagging	❌ Object tagging not supported
❌ PutObjectTagging	❌ Object tagging not supported
❌ DeleteObjectTagging	❌ Object tagging not supported
❌ GetObjectAttributes	❌ Not implemented
❌ GetObjectLegalHold	❌ Object locking not supported
❌ PutObjectLegalHold	❌ Object locking not supported
❌ GetObjectRetention	❌ Object retention not supported
❌ PutObjectRetention	❌ Object retention not supported
❌ SelectObjectContent	❌ S3 Select not supported
❌ RestoreObject	❌ Glacier operations not supported
❌ DeleteObjects	❌ Batch delete not supported

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.

S3 compatibility cannot be changed after storage zone creation.

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:

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

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

Use an SDK to interact with the S3 api
Enable Replication for at least one additional region
Implement retry logic for transient failures
Use multipart uploads for objects larger than 100MB
Include Content-Type headers when uploading, or rely on automatic detection
Handle pagination properly when listing objects or parts (max 1000 per request)
Monitor multipart sessions and abort abandoned uploads to free storage
Set presigned URL expiry time in seconds --expires-in 3600 = 1hour

​Creating a storage zone with S3 compatibility

​Quickstart

​Authentication and credentials

​Content Type Detection

​Checksum Validation

​Presigned URL Validation

​Examples

​AWS CLI

​rclone

​Supported S3 operations

​Object operations

​Directory listing

​Multipart upload operations

​S3 API compatibility matrix

​Unsupported operations

​Limits

​Regional availability

​Known limitations

​Error Codes

​Best Practices

Creating a storage zone with S3 compatibility

Quickstart

Authentication and credentials

Content Type Detection

Checksum Validation

Presigned URL Validation

Examples

AWS CLI

rclone

Supported S3 operations

Object operations

Directory listing

Multipart upload operations

S3 API compatibility matrix

Unsupported operations

Limits

Regional availability

Known limitations

Error Codes

Best Practices