Static Websites API: Deploy and Manage Sites

Static websites are frontend applications that Springwinter builds from your GitHub repository and serves globally via Amazon S3 and CloudFront — all inside your own AWS account. Springwinter handles the build pipeline, S3 bucket configuration, CloudFront distribution, cache invalidation on each deploy, and optional branch preview URLs. This approach gives you the performance of a global CDN with the data sovereignty and cost visibility of your own infrastructure. All requests require a valid Authorization: Bearer <token> header or an active cookie session with a CSRF token.

Launch a Static Website

POST /api/projects/{project_id}/static_websites

Creates and deploys a new static website. Springwinter clones the repository, runs your build command, uploads the output to S3, and creates a CloudFront distribution pointing at the bucket.

Path Parameters

string

required

The ID of the project that will own this static website.

Body Parameters

string

required

Display name for the static website. Used in the dashboard and to derive the CloudFront subdomain.

string

required

GitHub repository full name in owner/repo format (e.g. acme/marketing-site). The Springwinter GitHub App must already be installed on this repository.

string

required

Git branch to build and deploy (e.g. main).

string

required

Shell command Springwinter runs to produce the static output (e.g. npm run build or hugo).

string

required

Directory that contains the built output files to upload to S3 (e.g. dist, out, public).

boolean

default:"false"

When true, Springwinter automatically rebuilds and deploys the site on every push to the configured branch.

{
  "name": "marketing-site",
  "repo": "acme/marketing-site",
  "branch": "main",
  "build_command": "npm run build",
  "publish_dir": "dist",
  "auto_deploy": true
}

Response — `201 Created`

{
  "id": "sw_01h8xkr2m4fgz3nvq7p0c5w9",
  "name": "marketing-site",
  "status": "deploying",
  "url": "https://marketing-site.storefront.springwinter.app",
  "repo": "acme/marketing-site",
  "branch": "main",
  "build_command": "npm run build",
  "publish_dir": "dist",
  "auto_deploy": true
}

Get a Static Website

GET /api/projects/{project_id}/static_websites/{id}

Returns the current configuration and deployment status of a static website.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Response

{
  "id": "sw_01h8xkr2m4fgz3nvq7p0c5w9",
  "name": "marketing-site",
  "status": "running",
  "url": "https://marketing-site.storefront.springwinter.app",
  "repo": "acme/marketing-site",
  "branch": "main",
  "build_command": "npm run build",
  "publish_dir": "dist",
  "auto_deploy": true
}

Update a Static Website

PATCH /api/projects/{project_id}/static_websites/{id}

Updates one or more mutable settings on a static website. Changing build settings or the source branch triggers an automatic rebuild and redeploy.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website to update.

Body Parameters

string

Switch deployments to a different Git branch.

string

Updated build command.

string

Updated publish directory.

boolean

Enable or disable automatic deployments on push.

Response

Returns the updated static website object with "status": "deploying" if a rebuild was triggered.

{
  "id": "sw_01h8xkr2m4fgz3nvq7p0c5w9",
  "name": "marketing-site",
  "status": "deploying",
  "url": "https://marketing-site.storefront.springwinter.app",
  "repo": "acme/marketing-site",
  "branch": "release",
  "build_command": "npm run build",
  "publish_dir": "dist",
  "auto_deploy": true
}

Delete a Static Website

DELETE /api/projects/{project_id}/static_websites/{id}

Tears down the CloudFront distribution, empties and deletes the S3 bucket, and removes all other AWS resources associated with this site. This operation is irreversible.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website to delete.

Response — `204 No Content`

An empty body on success.

Redeploy a Static Website

POST /api/projects/{project_id}/static_websites/{id}/redeploy

Triggers an immediate rebuild and redeploy from the current branch, regardless of whether any new commits exist. Springwinter runs the build command, syncs the output to S3, and issues a CloudFront cache invalidation.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Response — `202 Accepted`

{
  "status": "deploying"
}

Get Build Logs

GET /api/projects/{project_id}/static_websites/{id}/logs

Returns log lines from the most recent build run for this static website. Build logs capture the output of your build_command and Springwinter’s S3 upload step.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Response

{
  "lines": [
    {
      "timestamp": "2024-06-01T14:00:01Z",
      "message": "Running build command: npm run build"
    },
    {
      "timestamp": "2024-06-01T14:00:28Z",
      "message": "Build succeeded. Uploading 412 files to S3..."
    },
    {
      "timestamp": "2024-06-01T14:00:31Z",
      "message": "Upload complete. Issuing CloudFront invalidation."
    }
  ]
}

Get Metrics

GET /api/projects/{project_id}/static_websites/{id}/metrics

Returns CloudFront and S3 metrics for the static website including request count, bytes transferred, and error rate.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Response

{
  "requests_1h": 52341,
  "bytes_transferred_1h": 4831200000,
  "error_rate_percent": 0.03,
  "cache_hit_rate_percent": 97.8
}

Get Cost Estimate

GET /api/projects/{project_id}/static_websites/{id}/cost

Returns the estimated spend to date this month and the projected monthly run rate for this static website based on CloudFront data transfer, S3 storage, and request counts.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Response

{
  "spend_this_month_usd": 0.94,
  "monthly_run_rate_usd": 3.10,
  "currency": "USD"
}

Get Environment Variables

GET /api/projects/{project_id}/static_websites/{id}/environment

Returns the build-time environment variables injected into the static website’s build command.

Environment variables for static websites are build-time only. They are available during build_command execution (e.g. as VITE_ or NEXT_PUBLIC_ prefixed variables that get inlined into your bundle), but they are not injected at runtime into the served files. Changing environment variables triggers a full rebuild so the new values are baked into the next deployment.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Response

{
  "environment": [
    { "name": "VITE_API_URL", "value": "https://api.storefront.springwinter.app" },
    { "name": "VITE_ANALYTICS_ID", "value": "UA-123456789-1" }
  ]
}

Replace Environment Variables

PUT /api/projects/{project_id}/static_websites/{id}/environment

Replaces the complete set of build-time environment variables for this static website and triggers a rebuild so the new values are baked into the next deployment.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Body Parameters

array

required

Array of { "name": string, "value": string } objects. This list fully replaces the existing build environment — any variable not included in the request is removed.

This endpoint performs a full replacement, not a merge. Any environment variable you omit from the request body will be permanently deleted. Fetch the current environment with GET .../environment first, merge your changes, and then submit the complete list. Because these variables are build-time only, a new deployment is triggered automatically after each successful PUT.

{
  "environment": [
    { "name": "VITE_API_URL", "value": "https://api.storefront.springwinter.app" },
    { "name": "VITE_ANALYTICS_ID", "value": "UA-123456789-1" },
    { "name": "VITE_FEATURE_FLAG", "value": "true" }
  ]
}

Response — `202 Accepted`

{
  "status": "deploying"
}

Previews

Static website previews let you deploy every branch to its own CloudFront distribution with a unique URL. This is ideal for design review, stakeholder sign-off, and end-to-end testing before merging into the production branch.

Create a Preview

POST /api/projects/{project_id}/static_websites/{id}/previews

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

Body Parameters

string

required

The Git branch to build and deploy as a preview site.

{ "branch": "feat/homepage-redesign" }

Response — 201 Created

{
  "id": "prev_05m2bos6q8jke7ryu1t4g9a3",
  "branch": "feat/homepage-redesign",
  "url": "https://marketing-site-feat-homepage-redesign.storefront.springwinter.app",
  "status": "deploying"
}

Get a Preview

GET /api/projects/{project_id}/static_websites/{id}/previews/{preview_id}

Returns the preview object including its URL, source branch, and current status.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

string

required

The unique ID of the preview deployment.

Response

{
  "id": "prev_05m2bos6q8jke7ryu1t4g9a3",
  "branch": "feat/homepage-redesign",
  "url": "https://marketing-site-feat-homepage-redesign.storefront.springwinter.app",
  "status": "running"
}

Delete a Preview

DELETE /api/projects/{project_id}/static_websites/{id}/previews/{preview_id}

Empties the preview S3 bucket, removes the CloudFront distribution, and clears all DNS records for the preview URL.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

string

required

The unique ID of the preview deployment to delete.

Response — `204 No Content`

An empty body on success.

Springwinter can automatically delete previews when their source branch is merged or deleted in GitHub. Enable this in your project’s GitHub settings to keep your AWS account free of stale CloudFront distributions.

Preview Build Logs

GET /api/projects/{project_id}/static_websites/{id}/previews/{preview_id}/logs

Returns build log lines for the preview deployment in the same format as the main site logs endpoint.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

string

required

The unique ID of the preview deployment.

Response

{
  "lines": [
    {
      "timestamp": "2024-06-01T16:00:01Z",
      "message": "Running build command: npm run build"
    },
    {
      "timestamp": "2024-06-01T16:00:24Z",
      "message": "Build succeeded. Uploading 412 files to S3..."
    },
    {
      "timestamp": "2024-06-01T16:00:27Z",
      "message": "Upload complete. Issuing CloudFront invalidation."
    }
  ]
}

Preview Metrics

GET /api/projects/{project_id}/static_websites/{id}/previews/{preview_id}/metrics

Returns CloudFront request and error metrics for the preview deployment.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

string

required

The unique ID of the preview deployment.

Response

{
  "requests_1h": 87,
  "bytes_transferred_1h": 9830400,
  "error_rate_percent": 0.0,
  "cache_hit_rate_percent": 94.3
}

Preview Environment Variables

GET /api/projects/{project_id}/static_websites/{id}/previews/{preview_id}/environment

Returns the build-time environment variables used when the preview was last built. These are the values that were baked into the preview’s static assets at build time.

Path Parameters

string

required

The ID of the project that owns the static website.

string

required

The unique ID of the static website.

string

required

The unique ID of the preview deployment.

Response

{
  "environment": [
    { "name": "VITE_API_URL", "value": "https://api.storefront.springwinter.app" },
    { "name": "VITE_ANALYTICS_ID", "value": "UA-123456789-1" },
    { "name": "VITE_FEATURE_FLAG", "value": "true" }
  ]
}

​Launch a Static Website

​Path Parameters

​Body Parameters

​Response — 201 Created

​Get a Static Website

​Path Parameters

​Response

​Update a Static Website

​Path Parameters

​Body Parameters

​Response

​Delete a Static Website

​Path Parameters

​Response — 204 No Content

​Redeploy a Static Website

​Path Parameters

​Response — 202 Accepted

​Get Build Logs

​Path Parameters

​Response

​Get Metrics

​Path Parameters

​Response

​Get Cost Estimate

​Path Parameters

​Response

​Get Environment Variables

​Path Parameters

​Response

​Replace Environment Variables

​Path Parameters

​Body Parameters

​Response — 202 Accepted

​Previews

​Create a Preview

​Path Parameters

​Body Parameters

​Get a Preview

​Path Parameters

​Response

​Delete a Preview

​Path Parameters

​Response — 204 No Content

​Preview Build Logs

​Path Parameters

​Response

​Preview Metrics

​Path Parameters

​Response

​Preview Environment Variables

​Path Parameters

​Response

Launch a Static Website

Path Parameters

Body Parameters

Response — `201 Created`

Get a Static Website

Path Parameters

Response

Update a Static Website

Path Parameters

Body Parameters

Response

Delete a Static Website

Path Parameters

Response — `204 No Content`

Redeploy a Static Website

Path Parameters

Response — `202 Accepted`

Get Build Logs

Path Parameters

Response

Get Metrics

Path Parameters

Response

Get Cost Estimate

Path Parameters

Response

Get Environment Variables

Path Parameters

Response

Replace Environment Variables

Path Parameters

Body Parameters

Response — `202 Accepted`

Previews

Create a Preview

Path Parameters

Body Parameters

Get a Preview

Path Parameters

Response

Delete a Preview

Path Parameters

Response — `204 No Content`

Preview Build Logs

Path Parameters

Response

Preview Metrics

Path Parameters

Response

Preview Environment Variables

Path Parameters

Response