> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Workers API: Deploy and Manage Background Services

> Launch, update, redeploy, and monitor background worker services in your AWS account using the Springwinter Workers API.

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

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that will own this worker.
</ParamField>

### Body Parameters

<ParamField body="name" type="string" required>
  Display name for the worker. Used in the dashboard and CloudWatch log group names.
</ParamField>

<ParamField body="repo" type="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.
</ParamField>

<ParamField body="branch" type="string" required>
  Git branch to build and deploy (e.g. `main`).
</ParamField>

<ParamField body="start_command" type="string" required>
  Shell command Springwinter uses as the container entry point (e.g. `node dist/worker.js` or `python -m myapp.worker`).
</ParamField>

<ParamField body="cpu" type="integer" required>
  ECS task CPU units. Valid values: `256`, `512`, `1024`, `2048`, `4096`.
</ParamField>

<ParamField body="memory" type="integer" required>
  ECS task memory in MiB. Must be a valid combination for the chosen `cpu` value per AWS Fargate sizing rules.
</ParamField>

<ParamField body="auto_deploy" type="boolean" default="false">
  When `true`, Springwinter automatically redeploys the worker on every push to the configured branch.
</ParamField>

<Note>
  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.
</Note>

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

```http theme={null}
GET /api/projects/{project_id}/workers/{id}
```

Returns the current configuration and status of a worker.

### Path Parameters

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

### Response

```json theme={null}
{
  "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

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker to update.
</ParamField>

### Body Parameters

<ParamField body="branch" type="string">
  Switch deployments to a different Git branch.
</ParamField>

<ParamField body="start_command" type="string">
  Updated container entry point command.
</ParamField>

<ParamField body="cpu" type="integer">
  Updated CPU units. Triggers a task-definition replacement and rolling redeploy.
</ParamField>

<ParamField body="memory" type="integer">
  Updated memory in MiB.
</ParamField>

<ParamField body="auto_deploy" type="boolean">
  Enable or disable automatic deployments on push.
</ParamField>

### Response

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

```json theme={null}
{
  "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

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker to delete.
</ParamField>

### Response — `204 No Content`

An empty body on success.

***

## Redeploy a Worker

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

### Response — `202 Accepted`

```json theme={null}
{
  "status": "deploying"
}
```

***

## Get Logs

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

### Response

```json theme={null}
{
  "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

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

### Response

```json theme={null}
{
  "cpu_utilization_percent": 8.2,
  "memory_utilization_percent": 31.7
}
```

***

## Get Cost Estimate

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

### Response

```json theme={null}
{
  "spend_this_month_usd": 1.84,
  "monthly_run_rate_usd": 6.20,
  "currency": "USD"
}
```

***

## Get Environment Variables

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/environment
```

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

### Path Parameters

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

### Response

```json theme={null}
{
  "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

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

### Body Parameters

<ParamField body="environment" type="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.
</ParamField>

<Warning>
  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.
</Warning>

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

```http theme={null}
POST /api/projects/{project_id}/workers/{id}/previews
```

#### Path Parameters

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

#### Body Parameters

<ParamField body="branch" type="string" required>
  The Git branch to build and deploy as a preview worker.
</ParamField>

```json theme={null}
{ "branch": "feat/new-queue-handler" }
```

**Response — `201 Created`**

```json theme={null}
{
  "id": "prev_04l1anr5p7ijd6qxt0s3f8z2",
  "branch": "feat/new-queue-handler",
  "status": "deploying"
}
```

<Note>
  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.
</Note>

***

### Get a Preview

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/previews/{preview_id}
```

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

#### Path Parameters

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

<ParamField path="preview_id" type="string" required>
  The unique ID of the preview deployment.
</ParamField>

#### Response

```json theme={null}
{
  "id": "prev_04l1anr5p7ijd6qxt0s3f8z2",
  "branch": "feat/new-queue-handler",
  "status": "running"
}
```

***

### Delete a Preview

```http theme={null}
DELETE /api/projects/{project_id}/workers/{id}/previews/{preview_id}
```

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

#### Path Parameters

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

<ParamField path="preview_id" type="string" required>
  The unique ID of the preview deployment to delete.
</ParamField>

#### Response — `204 No Content`

An empty body on success.

***

### Preview Logs

```http theme={null}
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

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

<ParamField path="preview_id" type="string" required>
  The unique ID of the preview deployment.
</ParamField>

#### Response

```json theme={null}
{
  "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

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/previews/{preview_id}/metrics
```

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

#### Path Parameters

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

<ParamField path="preview_id" type="string" required>
  The unique ID of the preview deployment.
</ParamField>

#### Response

```json theme={null}
{
  "cpu_utilization_percent": 5.1,
  "memory_utilization_percent": 22.3
}
```

***

### Preview Environment Variables

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/previews/{preview_id}/environment
```

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

#### Path Parameters

<ParamField path="project_id" type="string" required>
  The ID of the project that owns the worker.
</ParamField>

<ParamField path="id" type="string" required>
  The unique ID of the worker.
</ParamField>

<ParamField path="preview_id" type="string" required>
  The unique ID of the preview deployment.
</ParamField>

#### Response

```json theme={null}
{
  "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" }
  ]
}
```