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.
Bucket management endpoints allow you to create, configure, and manage S3 buckets in your Garage cluster.
List Buckets Returns all buckets in the cluster with their IDs and aliases.
Response Array of bucket information objects Bucket creation date (ISO 8601 format)
List of global aliases for this bucket
List of local aliases for this bucket Access key ID that owns this alias
Example curl -H 'Authorization: Bearer s3cr3t' \ http://localhost:3903/v2/ListBuckets | jq
[ { "id" : "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a" , "created" : "2025-06-15T10:23:45.123Z" , "globalAliases" : [ "my-bucket" ], "localAliases" : [ { "accessKeyId" : "GK31c2f218a2e44f485b94239e" , "alias" : "my-local-bucket" } ] } ]
Get Bucket Info Returns detailed information about a specific bucket.
Query Parameters Exact bucket ID to look up (hex-encoded)
Global alias of bucket to look up
Partial ID or alias to search for
You must specify exactly one of: id, globalAlias, or search
Response Bucket creation date (ISO 8601)
Whether website access is enabled
Website configuration (if enabled) Index document filename (e.g., “index.html”)
Error document filename (e.g., “error.html”)
Access keys with permissions on this bucket Permissions granted to this key Local aliases for this bucket under this key
Number of objects in the bucket
Total bytes used by objects
Number of unfinished uploads
unfinishedMultipartUploads
Number of unfinished multipart uploads
Bucket quotas Maximum bucket size in bytes (null for unlimited)
Maximum number of objects (null for unlimited)
Example curl -H 'Authorization: Bearer s3cr3t' \ 'http://localhost:3903/v2/GetBucketInfo?globalAlias=my-bucket' | jq
{ "id" : "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a" , "created" : "2025-06-15T10:23:45.123Z" , "globalAliases" : [ "my-bucket" ], "websiteAccess" : false , "websiteConfig" : null , "keys" : [ { "accessKeyId" : "GK31c2f218a2e44f485b94239e" , "name" : "my-key" , "permissions" : { "read" : true , "write" : true , "owner" : false }, "bucketLocalAliases" : [] } ], "objects" : 42 , "bytes" : 3145728 , "unfinishedUploads" : 0 , "unfinishedMultipartUploads" : 0 , "quotas" : { "maxSize" : null , "maxObjects" : null } }
Create Bucket Creates a new bucket with optional global or local aliases.
Request Body Global alias for the bucket
Local alias configuration Access key ID that will own this alias
Initial permissions to grant You can specify both globalAlias and localAlias to create two aliases at once.
Response Returns the same response as GetBucketInfo.
Example: Create with Global Alias curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{"globalAlias": "my-new-bucket"}' \ http://localhost:3903/v2/CreateBucket
Example: Create with Local Alias and Permissions curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "localAlias": { "accessKeyId": "GK31c2f218a2e44f485b94239e", "alias": "my-local-bucket", "allow": { "read": true, "write": true, "owner": false } } }' \ http://localhost:3903/v2/CreateBucket
Update Bucket Updates bucket configuration including website settings and quotas.
POST /v2/UpdateBucket?id= < bucket-i d >
Query Parameters ID of the bucket to update (hex-encoded)
Request Body Website access configuration Enable or disable website access
Index document (required if enabled=true)
Error document (optional)
Bucket quotas Maximum size in bytes (null for unlimited)
Maximum number of objects (null for unlimited)
When updating quotas, both maxSize and maxObjects must be specified. Set both to null to remove quotas.
Example: Enable Website curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "websiteAccess": { "enabled": true, "indexDocument": "index.html", "errorDocument": "error.html" } }' \ 'http://localhost:3903/v2/UpdateBucket?id=70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a'
Example: Set Quotas curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "quotas": { "maxSize": 107374182400, "maxObjects": 100000 } }' \ 'http://localhost:3903/v2/UpdateBucket?id=70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a'
Delete Bucket Deletes an empty bucket and all its aliases.
POST /v2/DeleteBucket?id= < bucket-i d >
Query Parameters ID of the bucket to delete (hex-encoded)
This will delete all aliases associated with the bucket! The bucket must be empty before deletion.
Example curl -X POST -H 'Authorization: Bearer s3cr3t' \ 'http://localhost:3903/v2/DeleteBucket?id=70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a'
Error Responses
400 Bad Request: Bucket is not empty404 Not Found: Bucket not found
Add Bucket Alias Adds a global or local alias to a bucket.
Request Body For Global Alias: For Local Alias: Access key ID that will own this alias
Example: Add Global Alias curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "bucketId": "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a", "globalAlias": "my-bucket-alias" }' \ http://localhost:3903/v2/AddBucketAlias
Example: Add Local Alias curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "bucketId": "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a", "accessKeyId": "GK31c2f218a2e44f485b94239e", "localAlias": "my-local-alias" }' \ http://localhost:3903/v2/AddBucketAlias
Remove Bucket Alias Removes a global or local alias from a bucket.
POST /v2/RemoveBucketAlias
Request Body Same format as AddBucketAlias.
Example curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "bucketId": "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a", "globalAlias": "my-bucket-alias" }' \ http://localhost:3903/v2/RemoveBucketAlias
Allow Bucket Key Grants permissions for an access key on a bucket.
Request Body Permissions to grant If true, grant read permission; if false, keep existing permission
If true, grant write permission; if false, keep existing permission
If true, grant owner permission; if false, keep existing permission
Unconventional Semantics: Setting a permission to true grants it. Setting to false keeps the existing permission unchanged. To deny permissions, use DenyBucketKey.
Example curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "bucketId": "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a", "accessKeyId": "GK31c2f218a2e44f485b94239e", "permissions": { "read": true, "write": true, "owner": false } }' \ http://localhost:3903/v2/AllowBucketKey
Deny Bucket Key Revokes permissions for an access key on a bucket.
Request Body Same format as AllowBucketKey.
Unconventional Semantics: Setting a permission to true revokes it. Setting to false keeps the existing permission unchanged.
Example curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "bucketId": "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a", "accessKeyId": "GK31c2f218a2e44f485b94239e", "permissions": { "read": true, "write": false, "owner": false } }' \ http://localhost:3903/v2/DenyBucketKey
Cleanup Incomplete Uploads Removes incomplete multipart uploads older than a specified number of seconds.
POST /v2/CleanupIncompleteUploads
Request Body Delete uploads older than this many seconds
Response Number of uploads that were deleted
Example # Delete incomplete uploads older than 7 days curl -X POST -H 'Authorization: Bearer s3cr3t' \ -H 'Content-Type: application/json' \ -d '{ "bucketId": "70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a", "olderThanSecs": 604800 }' \ http://localhost:3903/v2/CleanupIncompleteUploads
Inspect Object Returns detailed internal information about an object in a bucket.
GET /v2/InspectObject?bucketId= < bucket-i d >& key= < object-ke y >
Query Parameters Response Array of object versions Version UUID (hex-encoded)
Version timestamp (ISO 8601)
Whether the object is encrypted
Whether this version is currently uploading
Whether this is a delete marker
Data blocks for this version
Example curl -H 'Authorization: Bearer s3cr3t' \ 'http://localhost:3903/v2/InspectObject?bucketId=70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a&key=myfile.txt' | jq
