Bucket Management

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.

GET /v2/ListBuckets

Response

buckets

array

required

Array of bucket information objects

Show Bucket Object

string

Bucket ID (hex-encoded)

created

string

Bucket creation date (ISO 8601 format)

globalAliases

array

List of global aliases for this bucket

localAliases

array

List of local aliases for this bucket

Show Local Alias Object

accessKeyId

string

Access key ID that owns this alias

alias

string

Local alias name

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.

GET /v2/GetBucketInfo

Query Parameters

string

Exact bucket ID to look up (hex-encoded)

globalAlias

string

Global alias of bucket to look up

string

Partial ID or alias to search for

You must specify exactly one of: id, globalAlias, or search

Response

string

required

Bucket ID (hex-encoded)

created

string

required

Bucket creation date (ISO 8601)

globalAliases

array

required

List of global aliases

websiteAccess

boolean

required

Whether website access is enabled

websiteConfig

object

Website configuration (if enabled)

Show Website Config

indexDocument

string

Index document filename (e.g., “index.html”)

errorDocument

string

Error document filename (e.g., “error.html”)

keys

array

required

Access keys with permissions on this bucket

Show Key Object

accessKeyId

string

Access key ID

name

string

Key name

permissions

object

Permissions granted to this key

Show Permissions

read

boolean

Read permission

write

boolean

Write permission

owner

boolean

Owner permission

bucketLocalAliases

array

Local aliases for this bucket under this key

objects

integer

required

Number of objects in the bucket

bytes

integer

required

Total bytes used by objects

unfinishedUploads

integer

required

Number of unfinished uploads

unfinishedMultipartUploads

integer

required

Number of unfinished multipart uploads

quotas

object

required

Bucket quotas

Show Quotas

maxSize

integer

Maximum bucket size in bytes (null for unlimited)

maxObjects

integer

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.

POST /v2/CreateBucket

Request Body

globalAlias

string

Global alias for the bucket

localAlias

object

Local alias configuration

Show Local Alias Object

accessKeyId

string

required

Access key ID that will own this alias

alias

string

required

Local alias name

allow

object

Initial permissions to grant

Show Permissions

read

boolean

Grant read permission

write

boolean

Grant write permission

owner

boolean

Grant owner permission

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-id>

Query Parameters

string

required

ID of the bucket to update (hex-encoded)

Request Body

websiteAccess

object

Website access configuration

Show Website Access

enabled

boolean

required

Enable or disable website access

indexDocument

string

Index document (required if enabled=true)

errorDocument

string

Error document (optional)

quotas

object

Bucket quotas

Show Quotas

maxSize

integer

Maximum size in bytes (null for unlimited)

maxObjects

integer

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-id>

Query Parameters

string

required

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 empty
404 Not Found: Bucket not found

Add Bucket Alias

Adds a global or local alias to a bucket.

POST /v2/AddBucketAlias

Request Body

For Global Alias:

bucketId

string

required

Bucket ID (hex-encoded)

globalAlias

string

required

Global alias name

For Local Alias:

bucketId

string

required

Bucket ID (hex-encoded)

accessKeyId

string

required

Access key ID that will own this alias

localAlias

string

required

Local alias name

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.

POST /v2/AllowBucketKey

Request Body

bucketId

string

required

Bucket ID (hex-encoded)

accessKeyId

string

required

Access key ID

permissions

object

required

Permissions to grant

Show Permissions

read

boolean

If true, grant read permission; if false, keep existing permission

write

boolean

If true, grant write permission; if false, keep existing permission

owner

boolean

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.

POST /v2/DenyBucketKey

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

bucketId

string

required

Bucket ID (hex-encoded)

olderThanSecs

integer

required

Delete uploads older than this many seconds

Response

uploadsDeleted

integer

required

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

{
  "uploadsDeleted": 12
}

Inspect Object

Returns detailed internal information about an object in a bucket.

GET /v2/InspectObject?bucketId=<bucket-id>&key=<object-key>

Query Parameters

bucketId

string

required

Bucket ID (hex-encoded)

key

string

required

Object key (URL-encoded)

Response

bucketId

string

required

Bucket ID

key

string

required

Object key

versions

array

required

Array of object versions

Show Version Object

uuid

string

Version UUID (hex-encoded)

timestamp

string

Version timestamp (ISO 8601)

size

integer

Object size in bytes

etag

string

Object ETag

encrypted

boolean

Whether the object is encrypted

uploading

boolean

Whether this version is currently uploading

deleteMarker

boolean

Whether this is a delete marker

blocks

array

Data blocks for this version

Example

curl -H 'Authorization: Bearer s3cr3t' \
  'http://localhost:3903/v2/InspectObject?bucketId=70ec0cd3e60f0a6f934a1f1ab1e0c84e4b0e3e5a1c7e3b4a&key=myfile.txt' | jq

Overview

S3 API

Admin API

K2V API

Documentation Index

​List Buckets

​Response

​Example

​Get Bucket Info

​Query Parameters

​Response

​Example

​Create Bucket

​Request Body

​Response

​Example: Create with Global Alias

​Example: Create with Local Alias and Permissions

​Update Bucket

​Query Parameters

​Request Body

​Example: Enable Website

​Example: Set Quotas

​Delete Bucket

​Query Parameters

​Example

​Error Responses

​Add Bucket Alias

​Request Body

​Example: Add Global Alias

​Example: Add Local Alias

​Remove Bucket Alias

​Request Body

​Example

​Allow Bucket Key

​Request Body

​Example

​Deny Bucket Key

​Request Body

​Example

​Cleanup Incomplete Uploads

​Request Body

​Response

​Example

​Inspect Object

​Query Parameters

​Response

​Example

Build docs developers (and LLMs) love

List Buckets

Response

Example

Get Bucket Info

Query Parameters

Response

Example

Create Bucket

Request Body

Response

Example: Create with Global Alias

Example: Create with Local Alias and Permissions

Update Bucket

Query Parameters

Request Body

Example: Enable Website

Example: Set Quotas

Delete Bucket

Query Parameters

Example

Error Responses

Add Bucket Alias

Request Body

Example: Add Global Alias

Example: Add Local Alias

Remove Bucket Alias

Request Body

Example

Allow Bucket Key

Request Body

Example

Deny Bucket Key

Request Body

Example

Cleanup Incomplete Uploads

Request Body

Response

Example

Inspect Object

Query Parameters

Response

Example