Bucket Operations

All bucket operations require S3 authentication (SigV4). See S3 Setup for configuration.

CreateBucket

Creates a new bucket.

aws --profile oyster s3api create-bucket --bucket my-bucket

Response:

{
    "Location": "/my-bucket"
}

Bucket names follow the same naming rules as the JSON API: 3–63 characters, lowercase letters/digits/hyphens only, no consecutive hyphens, no IP address format, and no reserved names (health, ready, metrics, api).

Errors:

HeadBucket

Checks if a bucket exists and you have access to it. Returns no body — only HTTP status.

aws --profile oyster s3api head-bucket --bucket my-bucket

Returns exit code 0 on success (HTTP 200). If the bucket doesn't exist or isn't owned by your account, the AWS CLI prints an error (HTTP 404).

Errors:

ListBuckets

Lists all buckets in your account.

aws --profile oyster s3api list-buckets

Response:

{
    "Buckets": [
        {
            "Name": "my-bucket",
            "CreationDate": "2025-01-15T10:30:00Z"
        },
        {
            "Name": "logs-2025",
            "CreationDate": "2025-01-16T08:00:00Z"
        }
    ]
}

Returns up to 1000 buckets. No pagination is supported for this operation.

DeleteBucket

Deletes a bucket. The bucket must be empty first.

aws --profile oyster s3api delete-bucket --bucket my-bucket

Returns no output on success (HTTP 204).

Errors: