Workers API: Deploy and Manage Background Services

Workers are containerized background processes that Springwinter runs on Amazon ECS inside your AWS account. Unlike web servers, workers have no public URL or load balancer — they are designed for queue consumers, scheduled jobs, data pipelines, and any other workload that runs without serving inbound HTTP traffic. Springwinter manages the ECS task definition, IAM roles, CloudWatch logging, and compute sizing for you. All requests require a valid Authorization: Bearer <token> header or an active cookie session with a CSRF token.

Launch a Worker

POST /api/projects/{project_id}/workers

Creates and deploys a new background worker into the project. Springwinter pulls the source from the specified GitHub repository branch, builds the container image, pushes it to ECR, and starts the ECS service.

Path Parameters

string

required

The ID of the project that will own this worker.

Body Parameters

string

required

Display name for the worker. Used in the dashboard and CloudWatch log group names.

string

required

GitHub repository full name in owner/repo format (e.g. acme/jobs). 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 uses as the container entry point (e.g. node dist/worker.js or python -m myapp.worker).

integer

required

ECS task CPU units. Valid values: 256, 512, 1024, 2048, 4096.

integer

required

ECS task memory in MiB. Must be a valid combination for the chosen cpu value per AWS Fargate sizing rules.

boolean

default:"false"

When true, Springwinter automatically redeploys the worker on every push to the configured branch.

Workers have no public URL. There is no health_path field — Springwinter does not register workers with a load balancer or expose them to inbound traffic.

{
  "name": "email-dispatcher",
  "repo": "acme/jobs",
  "branch": "main",
  "start_command": "node dist/workers/email.js",
  "cpu": 256,
  "memory": 512,
  "auto_deploy": true
}

Response — `201 Created`

{
  "id": "wrk_01h8xkr2m4fgz3nvq7p0c5w9",
  "name": "email-dispatcher",
  "status": "deploying",
  "repo": "acme/jobs",
  "branch": "main",
  "start_command": "node dist/workers/email.js",
  "cpu": 256,
  "memory": 512,
  "auto_deploy": true
}

Get a Worker

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

Returns the current configuration and status of a worker.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Response

{
  "id": "wrk_01h8xkr2m4fgz3nvq7p0c5w9",
  "name": "email-dispatcher",
  "status": "running",
  "repo": "acme/jobs",
  "branch": "main",
  "start_command": "node dist/workers/email.js",
  "cpu": 256,
  "memory": 512,
  "auto_deploy": true
}

Update a Worker

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

Updates one or more mutable settings on a running worker. Changing source or compute settings triggers an automatic redeploy.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker to update.

Body Parameters

string

Switch deployments to a different Git branch.

string

Updated container entry point command.

integer

Updated CPU units. Triggers a task-definition replacement and rolling redeploy.

integer

Updated memory in MiB.

boolean

Enable or disable automatic deployments on push.

Response

Returns the updated worker object with "status": "deploying" if a redeploy was triggered.

{
  "id": "wrk_01h8xkr2m4fgz3nvq7p0c5w9",
  "name": "email-dispatcher",
  "status": "deploying",
  "repo": "acme/jobs",
  "branch": "main",
  "start_command": "node dist/workers/email.js",
  "cpu": 512,
  "memory": 1024,
  "auto_deploy": true
}

Delete a Worker

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

Tears down the ECS service and deletes the ECR repository for this worker. This operation is irreversible.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker to delete.

Response — `204 No Content`

An empty body on success.

Redeploy a Worker

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

Triggers an immediate redeploy from the current branch. Use this to apply environment variable changes, pick up a new base image, or recover from a failed deployment.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Response — `202 Accepted`

{
  "status": "deploying"
}

Get Logs

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

Returns recent log lines from the CloudWatch log group attached to this ECS service. Lines are returned in chronological order.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Response

{
  "lines": [
    {
      "timestamp": "2024-06-01T08:00:01Z",
      "message": "Worker started. Waiting for jobs..."
    },
    {
      "timestamp": "2024-06-01T08:00:45Z",
      "message": "Processing job id=e7f3a2 type=email_welcome"
    }
  ]
}

Get Metrics

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

Returns CloudWatch metrics for the worker, including CPU utilization and memory utilization gathered from the ECS task.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Response

{
  "cpu_utilization_percent": 8.2,
  "memory_utilization_percent": 31.7
}

Get Cost Estimate

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

Returns the estimated spend to date this month and the projected monthly run rate for this worker based on current ECS task sizes and uptime.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Response

{
  "spend_this_month_usd": 1.84,
  "monthly_run_rate_usd": 6.20,
  "currency": "USD"
}

Get Environment Variables

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

Returns the current set of ECS task environment variables configured for this worker.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Response

{
  "environment": [
    { "name": "QUEUE_URL", "value": "https://sqs.us-east-1.amazonaws.com/123456789012/jobs" },
    { "name": "DATABASE_URL", "value": "postgres://user:pass@db.storefront.springwinter.app/app" }
  ]
}

Replace Environment Variables

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

Replaces the complete set of ECS task environment variables for this worker and triggers a rolling redeploy so the new values take effect immediately.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Body Parameters

array

required

Array of { "name": string, "value": string } objects. This list fully replaces the existing 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.

{
  "environment": [
    { "name": "QUEUE_URL", "value": "https://sqs.us-east-1.amazonaws.com/123456789012/jobs" },
    { "name": "DATABASE_URL", "value": "postgres://user:pass@db.storefront.springwinter.app/app" },
    { "name": "LOG_LEVEL", "value": "info" }
  ]
}

Response — `202 Accepted`

{
  "status": "deploying"
}

Previews

Workers support branch preview deployments. Each preview runs an isolated ECS task from a different branch, which is useful for testing queue consumers, data pipelines, or cron job logic against a staging environment before merging.

Create a Preview

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

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

Body Parameters

string

required

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

{ "branch": "feat/new-queue-handler" }

Response — 201 Created

{
  "id": "prev_04l1anr5p7ijd6qxt0s3f8z2",
  "branch": "feat/new-queue-handler",
  "status": "deploying"
}

Worker previews do not have a public URL. You can distinguish preview traffic from production traffic by setting a dedicated environment variable (e.g. PREVIEW=true) when creating the preview, or by routing to a separate queue.

Get a Preview

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

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

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

string

required

The unique ID of the preview deployment.

Response

{
  "id": "prev_04l1anr5p7ijd6qxt0s3f8z2",
  "branch": "feat/new-queue-handler",
  "status": "running"
}

Delete a Preview

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

Tears down the preview ECS service and removes all associated AWS resources.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

string

required

The unique ID of the preview deployment to delete.

Response — `204 No Content`

An empty body on success.

Preview Logs

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

Returns CloudWatch log lines for the preview worker in the same format as the main worker logs endpoint.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

string

required

The unique ID of the preview deployment.

Response

{
  "lines": [
    {
      "timestamp": "2024-06-01T09:00:01Z",
      "message": "Preview worker started. Waiting for jobs..."
    },
    {
      "timestamp": "2024-06-01T09:00:30Z",
      "message": "Processing job id=f9a1b3 type=email_welcome"
    }
  ]
}

Preview Metrics

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

Returns CPU and memory utilization metrics for the preview worker deployment.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

string

required

The unique ID of the preview deployment.

Response

{
  "cpu_utilization_percent": 5.1,
  "memory_utilization_percent": 22.3
}

Preview Environment Variables

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

Returns the environment variables configured for this specific preview worker deployment.

Path Parameters

string

required

The ID of the project that owns the worker.

string

required

The unique ID of the worker.

string

required

The unique ID of the preview deployment.

Response

{
  "environment": [
    { "name": "QUEUE_URL", "value": "https://sqs.us-east-1.amazonaws.com/123456789012/jobs-preview" },
    { "name": "DATABASE_URL", "value": "postgres://user:pass@db.storefront.springwinter.app/app_preview" },
    { "name": "LOG_LEVEL", "value": "debug" }
  ]
}

​Launch a Worker

​Path Parameters

​Body Parameters

​Response — 201 Created

​Get a Worker

​Path Parameters

​Response

​Update a Worker

​Path Parameters

​Body Parameters

​Response

​Delete a Worker

​Path Parameters

​Response — 204 No Content

​Redeploy a Worker

​Path Parameters

​Response — 202 Accepted

​Get 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 Logs

​Path Parameters

​Response

​Preview Metrics

​Path Parameters

​Response

​Preview Environment Variables

​Path Parameters

​Response

Launch a Worker

Path Parameters

Body Parameters

Response — `201 Created`

Get a Worker

Path Parameters

Response

Update a Worker

Path Parameters

Body Parameters

Response

Delete a Worker

Path Parameters

Response — `204 No Content`

Redeploy a Worker

Path Parameters

Response — `202 Accepted`

Get 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 Logs

Path Parameters

Response

Preview Metrics

Path Parameters

Response

Preview Environment Variables

Path Parameters

Response