Storage API: Manage Private S3 Buckets

The Storage API lets you create and manage private S3 buckets that live directly in your AWS account. Buckets are private by default and are accessible to your web servers and workers through IAM role permissions that Springwinter manages for you. Use these endpoints to provision buckets, update their configuration, review CloudWatch storage metrics, and estimate AWS costs.

List Buckets

GET /api/projects//storage Return all storage buckets that exist within the specified project.

curl https://springwinter.dev/api/projects/proj_abc123/storage \
  -H "Authorization: Bearer swt_yourtoken"

{
  "buckets": [
    {
      "id": "stor_def456",
      "name": "my-bucket",
      "arn": "arn:aws:s3:::my-bucket-proj-abc123",
      "region": "us-east-1",
      "status": "active",
      "created_at": "2025-01-15T11:00:00Z",
      "updated_at": "2025-01-15T11:02:10Z"
    }
  ]
}

array

Array of bucket objects for the project. Each object has the same shape as the single-bucket GET response.

Create a Bucket

POST /api/projects//storage Create a new private S3 bucket inside the specified project.

curl -X POST https://springwinter.dev/api/projects/proj_abc123/storage \
  -H "Authorization: Bearer swt_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-bucket" }'

{
  "id": "stor_def456",
  "name": "my-bucket",
  "arn": "arn:aws:s3:::my-bucket-proj-abc123",
  "region": "us-east-1",
  "status": "creating",
  "created_at": "2025-01-15T11:00:00Z"
}

string

required

A human-readable label for the bucket. Springwinter appends a unique suffix to the actual S3 bucket name to prevent global naming collisions.

string

Unique Springwinter identifier for this storage resource.

string

The label you provided at creation time.

string

The full Amazon Resource Name of the S3 bucket.

string

AWS region where the bucket was created, matching your project’s region.

string

Lifecycle state. One of creating, active, or deleting.

Get a Bucket

GET /api/projects//storage/ Return the name, region, ARN, and current status of a bucket.

curl https://springwinter.dev/api/projects/proj_abc123/storage/stor_def456 \
  -H "Authorization: Bearer swt_yourtoken"

{
  "id": "stor_def456",
  "name": "my-bucket",
  "arn": "arn:aws:s3:::my-bucket-proj-abc123",
  "region": "us-east-1",
  "status": "active",
  "created_at": "2025-01-15T11:00:00Z",
  "updated_at": "2025-01-15T11:02:10Z"
}

string

Unique storage resource identifier.

string

Human-readable bucket label.

string

Full S3 ARN, usable in IAM policies and SDK calls.

string

AWS region of the bucket.

string

Current lifecycle state of the bucket.

Update a Bucket

PATCH /api/projects//storage/ Update the display name or other mutable settings of an existing bucket. The underlying S3 bucket name does not change.

curl -X PATCH https://springwinter.dev/api/projects/proj_abc123/storage/stor_def456 \
  -H "Authorization: Bearer swt_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{ "name": "uploads-bucket" }'

{
  "id": "stor_def456",
  "name": "uploads-bucket",
  "arn": "arn:aws:s3:::my-bucket-proj-abc123",
  "region": "us-east-1",
  "status": "active"
}

string

Updated display label for the bucket. Only the Springwinter label changes — the actual S3 bucket name in AWS remains unchanged.

Delete a Bucket

DELETE /api/projects//storage/ Permanently delete a bucket and all of its contents.

Deleting a bucket removes all objects inside it permanently. This action cannot be undone and there is no recovery path. Ensure you have backed up any data you need before calling this endpoint.

curl -X DELETE https://springwinter.dev/api/projects/proj_abc123/storage/stor_def456 \
  -H "Authorization: Bearer swt_yourtoken"

{
  "id": "stor_def456",
  "status": "deleting"
}

Get Storage Metrics

GET /api/projects//storage//metrics Return CloudWatch metrics for the bucket, including request counts and data transfer volume.

curl https://springwinter.dev/api/projects/proj_abc123/storage/stor_def456/metrics \
  -H "Authorization: Bearer swt_yourtoken"

{
  "get_requests": 14832,
  "put_requests": 2047,
  "delete_requests": 103,
  "bytes_downloaded": 10737418240,
  "bytes_uploaded": 2147483648,
  "period_seconds": 86400
}

integer

Number of GET and HEAD requests in the reporting period.

integer

Number of PUT, POST, and COPY requests in the reporting period.

integer

Number of DELETE requests in the reporting period.

integer

Total bytes transferred out of the bucket.

integer

Total bytes written into the bucket.

integer

Length of the reporting window in seconds.

Get Storage Cost Estimate

GET /api/projects//storage//cost Returns a link to the AWS Cost Explorer page for this specific bucket so you can inspect spend with full AWS-native detail.

curl https://springwinter.dev/api/projects/proj_abc123/storage/stor_def456/cost \
  -H "Authorization: Bearer swt_yourtoken"

{
  "cost_explorer_url": "https://us-east-1.console.aws.amazon.com/cost-management/home#/custom?...",
  "estimated_monthly_usd": 4.27,
  "month_to_date_usd": 1.42,
  "currency": "USD"
}

string

A direct URL to AWS Cost Explorer pre-filtered for this bucket. Open it in your browser while logged in to your AWS account.

number

Springwinter’s projection of the full-month cost based on current usage, sourced from AWS Cost Explorer.

number

Actual AWS spend recorded so far this calendar month.

string

Currency code for all cost values. Always "USD".

Buckets are private by default and cannot be made public through the Storage API. If you need to serve files publicly over HTTPS, create a static website resource instead — Springwinter will provision an S3 bucket and CloudFront distribution configured for public access.

Overview

Projects & Resources

Data & Storage

Account

Storage API: Manage Private S3 Buckets

List Buckets

Create a Bucket

Get a Bucket

Update a Bucket

Delete a Bucket

Get Storage Metrics

Get Storage Cost Estimate

​List Buckets

​Create a Bucket

​Get a Bucket

​Update a Bucket

​Delete a Bucket

​Get Storage Metrics

​Get Storage Cost Estimate

List Buckets

Create a Bucket

Get a Bucket

Update a Bucket

Delete a Bucket

Get Storage Metrics

Get Storage Cost Estimate