Skip to main content

S3 Buckets

S3 buckets are logical containers for storing objects.

Important: You must create an S3 user in your project before you can create any S3 buckets.

S3 Bucket Schema​

  • name String - The globally unique name of the bucket.
  • owner String - The ID of the S3 user who owns the bucket.
  • created_at String - The timestamp when the bucket was created.

Create an S3 Bucket​

Creates a new S3 bucket.

POST /storage/v1/s3/buckets (HTTP 201 - Created)

Body parameters

  • name String Required - The unique name for the S3 bucket.
  • user_id String Required - The ID of the S3 user who will own the bucket.

Response Example

{
  "bucket": {
    "name": "my-bucket",
    "owner": "b77e0c79-159e-46e6-bcc8-cec8b18f0d1a",
    "created_at": "2026-06-16T14:54:58.101526+00:00"
  }
}

List S3 Buckets​

Lists all S3 buckets in your project.

GET /storage/v1/s3/buckets (HTTP 200 - OK)

Response Example

{
  "buckets": [
    {
      "name": "my-bucket",
      "owner": "b77e0c79-159e-46e6-bcc8-cec8b18f0d1a",
      "created_at": "2026-06-16T14:54:58.101526+00:00"
    }
  ],
  "total_count": 1
}

Delete S3 Bucket​

Delete an S3 bucket.

DELETE /storage/v1/s3/buckets/<bucket_name> (HTTP 204 - No Content)

Examples (cURL)​

# Create an S3 bucket
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-bucket", "user_id": "b77e0c79-159e-46e6-bcc8-cec8b18f0d1a"}' \
  https://public-api.krs-1.epilayer.eu/storage/v1/s3/buckets

# List S3 buckets
curl -H "Authorization: Bearer $TOKEN" \
  https://public-api.krs-1.epilayer.eu/storage/v1/s3/buckets

# Delete an S3 bucket
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://public-api.krs-1.epilayer.eu/storage/v1/s3/buckets/my-bucket

Examples (Boto3)​

To interact with your buckets using the official AWS SDK for Python (boto3), you will need your S3 credentials and endpoint URL.

Tip: You can find these details by navigating to the S3 page in your project dashboard (e.g., https://console.nord-no-krs-1.sagadata.tum.fail/projects/<your-project-id>/s3) and clicking the ACCESS INFO button. For a full list of valid region codes, see our Regions documentation.

import boto3

# Configuration
endpoint_url = 'https://s3.<region>.epilayerusercontent.eu' # Replace <region> with your specific region code
access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY'
bucket_name = 'YOUR_BUCKET_NAME'

# Initialize S3 client
s3 = boto3.client(
    's3',
    endpoint_url=endpoint_url,
    aws_access_key_id=access_key,
    aws_secret_access_key=secret_key,
    verify=True # Set to False if using self-signed certificates
)

# Upload a file
file_path = "example.txt"
object_key = "folder/example.txt"
s3.upload_file(file_path, bucket_name, object_key)

# List objects in the bucket
response = s3.list_objects_v2(Bucket=bucket_name)

if 'Contents' in response:
    for obj in response['Contents']:
        print(obj['Key'])
else:
    print("Bucket is empty or does not exist.")