Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deuxfleurs-org/garage/llms.txt

Use this file to discover all available pages before exploring further.

This page documents the S3 API operations for managing buckets in Garage.

​
CreateBucket

Creates a new S3 bucket. 
PUT /{bucket} HTTP/1.1
Host: s3.garage.example.com

​
Request Body (Optional)

<CreateBucketConfiguration>
  <LocationConstraint>garage</LocationConstraint>
</CreateBucketConfiguration>
​
LocationConstraint
string
The region where the bucket should be created. Must match the Garage S3 region configuration.

​
Example

aws s3 mb s3://my-bucket --endpoint-url https://s3.garage.example.com
cURL
curl -X PUT https://s3.garage.example.com/my-bucket \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

​
Response

HTTP/1.1 200 OK
Location: /my-bucket

​
Error Responses

ErrorStatusDescription
BucketAlreadyOwnedByYou409You already own this bucket
BucketAlreadyExists409Bucket exists and is owned by another user
InvalidBucketName400Bucket name is invalid
The access key must have the allow_create_bucket permission enabled. Bucket names must follow S3 naming rules.

​
DeleteBucket

Deletes an empty bucket. 
DELETE /{bucket} HTTP/1.1
Host: s3.garage.example.com

​
Example

aws s3 rb s3://my-bucket --endpoint-url https://s3.garage.example.com
cURL
curl -X DELETE https://s3.garage.example.com/my-bucket \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

​
Response

HTTP/1.1 204 No Content

​
Error Responses

ErrorStatusDescription
BucketNotEmpty409Bucket contains objects and cannot be deleted
NoSuchBucket404Bucket does not exist
The bucket must be empty before it can be deleted. Use ListObjectsV2 and DeleteObjects to remove all objects first.

​
HeadBucket

Checks if a bucket exists and you have permission to access it. 
HEAD /{bucket} HTTP/1.1
Host: s3.garage.example.com

​
Example

cURL
curl -I https://s3.garage.example.com/my-bucket \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

​
Response

HTTP/1.1 200 OK

​
Error Responses

ErrorStatusDescription
NotFound404Bucket does not exist or access denied

​
ListBuckets

Returns a list of all buckets accessible to the authenticated user. 
GET / HTTP/1.1
Host: s3.garage.example.com

​
Example

aws s3 ls --endpoint-url https://s3.garage.example.com
cURL
curl https://s3.garage.example.com/ \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

​
Response

<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>GK...</ID>
    <DisplayName>my-key</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>my-bucket</Name>
      <CreationDate>2026-03-04T10:30:00.000Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

​
GetBucketLocation

Returns the region where a bucket is located. 
GET /{bucket}?location HTTP/1.1
Host: s3.garage.example.com

​
Example

aws s3api get-bucket-location --bucket my-bucket \
  --endpoint-url https://s3.garage.example.com

​
Response

<?xml version="1.0" encoding="UTF-8"?>
<LocationConstraint>garage</LocationConstraint>

​
ListObjects

Lists objects in a bucket (version 1). 
GET /{bucket}?list-type=1 HTTP/1.1
Host: s3.garage.example.com

​
Query Parameters

​
delimiter
string
Character used to group keys (commonly /)
​
encoding-type
string
Encoding for keys in the response. Supported value: url
​
marker
string
Key to start listing from (for pagination)
​
max-keys
integer
default:"1000"
Maximum number of keys to return (1-1000)
​
prefix
string
Limit results to keys that begin with this prefix

​
Example

aws s3api list-objects --bucket my-bucket \
  --endpoint-url https://s3.garage.example.com
ListObjectsV2 is recommended over ListObjects for new applications.

​
ListObjectsV2

Lists objects in a bucket (version 2, recommended). 
GET /{bucket}?list-type=2 HTTP/1.1
Host: s3.garage.example.com

​
Query Parameters

​
continuation-token
string
Token for pagination (from previous response)
​
delimiter
string
Character used to group keys
​
encoding-type
string
Encoding for keys in the response. Supported value: url
​
max-keys
integer
default:"1000"
Maximum number of keys to return (1-1000)
​
prefix
string
Limit results to keys that begin with this prefix
​
start-after
string
Key to start listing after

​
Example

aws s3api list-objects-v2 --bucket my-bucket --prefix "images/" \
  --endpoint-url https://s3.garage.example.com
cURL
curl "https://s3.garage.example.com/my-bucket?list-type=2&prefix=images/" \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

​
Response

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>my-bucket</Name>
  <Prefix>images/</Prefix>
  <KeyCount>2</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>images/photo1.jpg</Key>
    <LastModified>2026-03-04T10:30:00.000Z</LastModified>
    <ETag>&quot;abc123&quot;</ETag>
    <Size>1024000</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

​
GetBucketVersioning

Returns the versioning state of a bucket. 
GET /{bucket}?versioning HTTP/1.1
Host: s3.garage.example.com

​
Response

<?xml version="1.0" encoding="UTF-8"?>
<VersioningConfiguration/>
Garage does not support bucket versioning. This endpoint always returns that versioning is not enabled.

​
Additional Bucket Operations

Garage also implements the following bucket operations:

​
Website Hosting

  • GetBucketWebsite - Get website configuration
  • PutBucketWebsite - Configure static website hosting (partial support)
  • DeleteBucketWebsite - Remove website configuration
See the Static Website Hosting guide for details.

​
CORS

  • GetBucketCors - Get CORS configuration
  • PutBucketCors - Set CORS rules
  • DeleteBucketCors - Remove CORS configuration

​
Lifecycle

  • GetBucketLifecycleConfiguration - Get lifecycle rules
  • PutBucketLifecycleConfiguration - Set lifecycle rules (partial support)
  • DeleteBucketLifecycle - Remove lifecycle configuration
Lifecycle rules in Garage support only AbortIncompleteMultipartUpload and Expiration actions.

​
Unsupported Operations

The following bucket operations are not implemented in Garage:
  • Bucket policies (GetBucketPolicy, PutBucketPolicy, DeleteBucketPolicy)
  • Bucket ACLs (GetBucketAcl, PutBucketAcl)
  • Bucket versioning (PutBucketVersioning, ListObjectVersions)
  • Bucket encryption (GetBucketEncryption, PutBucketEncryption)
  • Bucket tagging, notifications, analytics, metrics, etc.
Garage uses its own permission system. See the Access Control guide for details.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us