Bucket Operations

Oyster supports 4 bucket operations through the S3 API: CreateBucket, HeadBucket, ListBuckets, and DeleteBucket. You run them with the AWS CLI.

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, and hyphens only, no consecutive hyphens, no IP address format, and no reserved names (health, ready, metrics, api).

Errors:

S3 error code	Condition
BucketAlreadyOwnedByYou	A bucket with this name already exists
InvalidBucketName	Name violates naming rules

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 your account doesn't own it, the AWS CLI prints an error (HTTP 404).

Errors:

HTTP status	Condition
404	Bucket doesn't exist or your account doesn't own it

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. This operation doesn't support pagination.

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:

S3 error code	Condition
NoSuchBucket	Bucket doesn't exist or your account doesn't own it
BucketNotEmpty	Bucket still contains objects

Does HeadBucket distinguish buckets owned by other accounts?

Oyster doesn't use a separate status code for a bucket that another account owns. It looks up the bucket by name and by your account together, so another account's bucket returns the same HTTP 404 as a bucket that doesn't exist.