GET /api/openapi.json; no token is needed to read it. Customer data and deployment operations still require authentication. The interactive reference is in the app.
Authenticated operations accept Authorization: Bearer $SPRINGWINTER_TOKEN. Cookie mutations require a CSRF token. Signed webhooks use their own signature checks. Read each operation’s security setting.
POST /api/projects/{project_id}/workers
Launch a worker
Checks the customer IAM role without ELBv2 actions, creates the Resource, and starts Worker::BuildAndDeploy. Rejects port and health_path. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Launch a worker",
"description": "Checks the customer IAM role without ELBv2 actions, creates the `Resource`, and starts `Worker::BuildAndDeploy`. Rejects `port` and `health_path`. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.",
"operationId": "createWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"worker"
],
"properties": {
"worker": {
"type": "object",
"required": [
"name",
"repository",
"dockerfile_path",
"vcpu",
"memory_gb",
"min_copies",
"max_copies"
],
"properties": {
"name": {
"type": "string"
},
"repository": {
"type": "string",
"example": "acme/jobs"
},
"dockerfile_path": {
"type": "string",
"example": "Dockerfile",
"description": "Path relative to the repository root, independent of root_directory."
},
"root_directory": {
"type": "string",
"default": ".",
"example": "server",
"description": "Docker build context relative to the repository root. Empty means the whole repository. Applies to GitHub builds only."
},
"container_command": {
"type": [
"string",
"null"
],
"description": "Replaces the image command. Blank keeps the Dockerfile command. The entrypoint still runs."
},
"vcpu": {
"type": "number",
"example": 0.5
},
"memory_gb": {
"type": "number",
"example": 1
},
"min_copies": {
"type": "integer",
"example": 1
},
"max_copies": {
"type": "integer",
"example": 2
},
"spot_mode": {
"type": "string",
"enum": [
"on_demand",
"spot_only",
"balanced"
],
"default": "on_demand",
"description": "Fargate capacity. Spot modes are rejected with a data volume. Applies on the next Redeploy."
},
"ebs_size_gib": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100
},
"ebs_mount_path": {
"type": [
"string",
"null"
],
"example": "/data"
},
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvironmentVariable"
},
"description": "Initial runtime environment. Values stay in AWS."
},
"build_variables": {
"type": "array",
"maxItems": 50,
"description": "Build-time variables for the first build. GitHub sources only. Values are held temporarily in customer AWS Secrets Manager, copied to CodeBuild, then the temporary copy is deleted. Dockerfiles require matching ARG declarations. Values can be embedded into images or public bundles.",
"items": {
"$ref": "#/components/schemas/EnvironmentVariable"
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Resource accepted; workflow started. This does not confirm deployment or teardown completion. Poll the resource GET and inspect workflow status until succeeded or failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkerContractMutation"
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidParameters"
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"initial_build_environment_unavailable",
"invalid_worker",
"missing_aws_account",
"missing_permissions",
"spot_unavailable_for_volume"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/workers/{id}
Show a worker
{
"tags": [
"Workers"
],
"summary": "Show a worker",
"operationId": "getWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"responses": {
"200": {
"description": "Resource and asynchronous workflow history. A public URL alone does not prove a successful deployment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkerContractShow"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
PATCH /api/projects/{project_id}/workers/{id}
Update desired source, compute, or auto-deploy
Writes root_directory, dockerfile_path, container_command, vcpu, memory_gb, min_copies, max_copies, deploy_branch_pattern, and/or ebs_size_gib with ebs_mount_path. dockerfile_path stays relative to the repository root. root_directory selects the Docker build context, defaults to ., and accepts an empty value to reset it. Both apply on the next Redeploy. container_command replaces the image command on the next Redeploy or Environment save; blank keeps the Dockerfile command. Rejects port and health_path. Does not start a workflow. A data volume applies on the next Redeploy. Null size and path clear it. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Update desired source, compute, or auto-deploy",
"description": "Writes `root_directory`, `dockerfile_path`, `container_command`, `vcpu`, `memory_gb`, `min_copies`, `max_copies`, `deploy_branch_pattern`, and/or `ebs_size_gib` with `ebs_mount_path`. `dockerfile_path` stays relative to the repository root. `root_directory` selects the Docker build context, defaults to `.`, and accepts an empty value to reset it. Both apply on the next Redeploy. `container_command` replaces the image command on the next Redeploy or Environment save; blank keeps the Dockerfile command. Rejects `port` and `health_path`. Does not start a workflow. A data volume applies on the next Redeploy. Null size and path clear it. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.",
"operationId": "updateWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"worker"
],
"properties": {
"worker": {
"type": "object",
"minProperties": 1,
"properties": {
"vcpu": {
"type": "number"
},
"memory_gb": {
"type": "number"
},
"min_copies": {
"type": "integer"
},
"max_copies": {
"type": "integer"
},
"spot_mode": {
"type": "string",
"enum": [
"on_demand",
"spot_only",
"balanced"
],
"description": "Fargate capacity. Rejected with a data volume. Applies on the next Redeploy."
},
"root_directory": {
"type": "string",
"default": ".",
"example": "server",
"description": "Docker build context relative to the repository root. Empty resets to the repository root."
},
"dockerfile_path": {
"type": "string",
"description": "Relative Dockerfile path in the repository. Applies on the next Redeploy."
},
"container_command": {
"type": "string",
"description": "Replaces the image command. Blank keeps the Dockerfile command. Applies on the next Redeploy or Environment save."
},
"deploy_branch_pattern": {
"type": "string",
"description": "Branch regex for GitHub push auto-deploy. Blank disables it."
},
"ebs_size_gib": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100
},
"ebs_mount_path": {
"type": [
"string",
"null"
]
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Desired configuration saved. No deployment workflow starts; redeploy to apply saved settings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/WorkerContractResource"
}
},
"required": [
"resource"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidParameters"
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_worker",
"spot_unavailable_for_volume"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
DELETE /api/projects/{project_id}/workers/{id}
Tear down a worker
Starts Worker::Teardown. The last compute resource also deletes the project VPC. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Tear down a worker",
"description": "Starts `Worker::Teardown`. The last compute resource also deletes the project VPC. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.",
"operationId": "deleteWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"responses": {
"202": {
"description": "Resource accepted; workflow started. This does not confirm deployment or teardown completion. Poll the resource GET and inspect workflow status until succeeded or failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkerContractMutation"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"previews_exist",
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_worker",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
PUT /api/projects/{project_id}/workers/{id}
Update desired source, compute, or auto-deploy
Writes root_directory, dockerfile_path, container_command, vcpu, memory_gb, min_copies, max_copies, deploy_branch_pattern, and/or ebs_size_gib with ebs_mount_path. dockerfile_path stays relative to the repository root. root_directory selects the Docker build context, defaults to ., and accepts an empty value to reset it. Both apply on the next Redeploy. container_command replaces the image command on the next Redeploy or Environment save; blank keeps the Dockerfile command. Rejects port and health_path. Does not start a workflow. A data volume applies on the next Redeploy. Null size and path clear it. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Update desired source, compute, or auto-deploy",
"description": "Writes `root_directory`, `dockerfile_path`, `container_command`, `vcpu`, `memory_gb`, `min_copies`, `max_copies`, `deploy_branch_pattern`, and/or `ebs_size_gib` with `ebs_mount_path`. `dockerfile_path` stays relative to the repository root. `root_directory` selects the Docker build context, defaults to `.`, and accepts an empty value to reset it. Both apply on the next Redeploy. `container_command` replaces the image command on the next Redeploy or Environment save; blank keeps the Dockerfile command. Rejects `port` and `health_path`. Does not start a workflow. A data volume applies on the next Redeploy. Null size and path clear it. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.",
"operationId": "replaceWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"worker"
],
"properties": {
"worker": {
"type": "object",
"minProperties": 1,
"properties": {
"vcpu": {
"type": "number"
},
"memory_gb": {
"type": "number"
},
"min_copies": {
"type": "integer"
},
"max_copies": {
"type": "integer"
},
"spot_mode": {
"type": "string",
"enum": [
"on_demand",
"spot_only",
"balanced"
],
"description": "Fargate capacity. Rejected with a data volume. Applies on the next Redeploy."
},
"root_directory": {
"type": "string",
"default": ".",
"example": "server",
"description": "Docker build context relative to the repository root. Empty resets to the repository root."
},
"dockerfile_path": {
"type": "string",
"description": "Relative Dockerfile path in the repository. Applies on the next Redeploy."
},
"container_command": {
"type": "string",
"description": "Replaces the image command. Blank keeps the Dockerfile command. Applies on the next Redeploy or Environment save."
},
"deploy_branch_pattern": {
"type": "string",
"description": "Branch regex for GitHub push auto-deploy. Blank disables it."
},
"ebs_size_gib": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100
},
"ebs_mount_path": {
"type": [
"string",
"null"
]
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Desired configuration saved. No deployment workflow starts; redeploy to apply saved settings.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/WorkerContractResource"
}
},
"required": [
"resource"
]
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidParameters"
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_worker",
"spot_unavailable_for_volume"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/workers/{id}/cost
Worker cost estimate
{
"tags": [
"Workers"
],
"summary": "Worker cost estimate",
"operationId": "getWorkerCost",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"responses": {
"200": {
"description": "Catalog cost estimate with cost_explorer_url",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CostPage"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/workers/{id}/environment
Read worker environment variables
Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS.
{
"tags": [
"Workers"
],
"summary": "Read worker environment variables",
"operationId": "getWorkerEnvironment",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"name": "scope",
"in": "query",
"schema": {
"type": "string",
"enum": [
"runtime",
"build"
]
}
}
],
"responses": {
"200": {
"description": "ECS task-definition variables",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnvironmentPage"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"environment_unavailable",
"invalid_environment",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
},
"description": "Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS."
}
PUT /api/projects/{project_id}/workers/{id}/environment
Replace worker environment variables
Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Replace worker environment variables",
"operationId": "updateWorkerEnvironment",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"environment"
],
"properties": {
"environment": {
"type": "object",
"properties": {
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvironmentVariable"
},
"description": "Full replacement list. Omitted variables is treated as [], clearing user variables."
},
"scope": {
"type": "string",
"enum": [
"runtime",
"build"
]
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated environment variables",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnvironmentPage"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"environment_unavailable",
"invalid_worker",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
},
"description": "Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets."
}
GET /api/projects/{project_id}/workers/{id}/logs
Worker logs
{
"tags": [
"Workers"
],
"summary": "Worker logs",
"operationId": "getWorkerLogs",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"name": "source",
"in": "query",
"schema": {
"type": "string",
"enum": [
"build",
"server"
]
}
},
{
"name": "run_id",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "filter",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "next_token",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Log events",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogPage"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"missing_permissions",
"unsupported_log_source"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/workers/{id}/metrics
Worker metrics
CPU, memory, and replica widgets. ALB request/5xx widgets are omitted unless the run stored a load balancer.
{
"tags": [
"Workers"
],
"summary": "Worker metrics",
"description": "CPU, memory, and replica widgets. ALB request/5xx widgets are omitted unless the run stored a load balancer.",
"operationId": "getWorkerMetrics",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Metric widgets",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricsPage"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
POST /api/projects/{project_id}/workers/{id}/pause
Pause worker
For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Pause worker",
"operationId": "pauseWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_availability_change",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"202": {
"description": "Resource accepted; workflow started. This does not confirm deployment or teardown completion. Poll the resource GET and inspect workflow status until succeeded or failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkerContractMutation"
}
}
}
}
},
"description": " For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets."
}
POST /api/projects/{project_id}/workers/{id}/previews
Create a preview of a worker
Creates a child from saved parent configuration. Requires a previous deployment and a GitHub source. Choose branch with branch, or commit with git_sha. A full 40-character SHA is accepted directly; other refs are resolved through GitHub. Public-image parents return invalid_preview. Child workflow success must be checked separately. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Create a preview of a worker",
"description": "Creates a child from saved parent configuration. Requires a previous deployment and a GitHub source. Choose branch with branch, or commit with git_sha. A full 40-character SHA is accepted directly; other refs are resolved through GitHub. Public-image parents return invalid_preview. Child workflow success must be checked separately. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.",
"operationId": "createWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"preview": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"branch",
"commit"
]
},
"branch": {
"type": "string"
},
"git_sha": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvironmentVariable"
},
"description": "Optional full initial environment override. Omitted copies parent variables; [] uses no variables."
}
},
"required": [
"source"
],
"oneOf": [
{
"properties": {
"source": {
"const": "branch"
}
},
"required": [
"branch"
]
},
{
"properties": {
"source": {
"const": "commit"
}
},
"required": [
"git_sha"
]
}
]
}
},
"required": [
"preview"
]
}
}
}
},
"responses": {
"201": {
"description": "Preview created and workflow started; deployment is asynchronous.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/ComputePreviewResource"
},
"workflow_run_id": {
"type": "string"
},
"preview": {
"$ref": "#/components/schemas/ComputePreview"
}
},
"required": [
"resource",
"workflow_run_id",
"preview"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_git_ref",
"invalid_preview",
"missing_aws_account",
"missing_permissions",
"no_previous_deployment"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/workers/{id}/previews/{preview_id}
Show a worker preview
{
"tags": [
"Workers"
],
"summary": "Show a worker preview",
"operationId": "getWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"$ref": "#/components/parameters/PreviewId"
}
],
"responses": {
"200": {
"description": "Preview and workflow state",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"preview": {
"$ref": "#/components/schemas/ComputePreview"
}
},
"required": [
"preview"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"preview_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
DELETE /api/projects/{project_id}/workers/{id}/previews/{preview_id}
Tear down a worker preview
For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Tear down a worker preview",
"operationId": "deleteWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"$ref": "#/components/parameters/PreviewId"
}
],
"responses": {
"202": {
"description": "Preview workflow started; completion is asynchronous.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/ComputePreviewResource"
},
"workflow_run_id": {
"type": "string"
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"preview_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_preview",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
},
"description": " For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets."
}
GET /api/projects/{project_id}/workers/{id}/previews/{preview_id}/environment
Environment preview
Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS.
{
"tags": [
"Workers"
],
"summary": "Environment preview",
"operationId": "environmentWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"$ref": "#/components/parameters/PreviewId"
},
{
"name": "scope",
"in": "query",
"schema": {
"type": "string",
"enum": [
"runtime",
"build"
]
}
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"preview_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"environment_unavailable",
"invalid_environment",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"200": {
"description": "ECS task-definition variables",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnvironmentPage"
}
}
}
}
},
"description": "Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS."
}
PUT /api/projects/{project_id}/workers/{id}/previews/{preview_id}/environment
Update Environment preview
Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Update Environment preview",
"operationId": "update_environmentWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"$ref": "#/components/parameters/PreviewId"
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"preview_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"environment_unavailable",
"invalid_environment",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"200": {
"description": "Updated environment variables",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnvironmentPage"
}
}
}
}
},
"description": "Omitted scope uses runtime variables. scope=build uses AWS CodeBuild variables for GitHub sources. Public-image sources reject build scope. Build saves apply on the next build and do not deploy. Docker builds require matching Dockerfile ARG names. Build values remain in AWS. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"environment"
],
"properties": {
"environment": {
"type": "object",
"properties": {
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvironmentVariable"
},
"description": "Full replacement list. Omitted variables is treated as [], clearing user variables."
},
"scope": {
"type": "string",
"enum": [
"runtime",
"build"
]
}
}
}
}
}
}
}
}
}
GET /api/projects/{project_id}/workers/{id}/previews/{preview_id}/logs
Logs preview
{
"tags": [
"Workers"
],
"summary": "Logs preview",
"operationId": "logsWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"$ref": "#/components/parameters/PreviewId"
},
{
"name": "source",
"in": "query",
"schema": {
"type": "string",
"enum": [
"build",
"server"
]
}
},
{
"name": "run_id",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "filter",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "next_token",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"preview_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"missing_permissions",
"unsupported_log_source"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"200": {
"description": "Preview observations",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogPage"
}
}
}
}
}
}
GET /api/projects/{project_id}/workers/{id}/previews/{preview_id}/metrics
Metrics preview
{
"tags": [
"Workers"
],
"summary": "Metrics preview",
"operationId": "metricsWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"$ref": "#/components/parameters/PreviewId"
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"preview_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"200": {
"description": "Preview observations",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricsPage"
}
}
}
}
}
}
POST /api/projects/{project_id}/workers/{id}/previews/{preview_id}/redeploy
Redeploy preview
For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Redeploy preview",
"operationId": "redeployWorkerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
},
{
"$ref": "#/components/parameters/PreviewId"
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"preview_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_preview",
"missing_aws_account",
"missing_permissions",
"no_previous_deployment"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"202": {
"description": "Preview workflow started; completion is asynchronous.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/ComputePreviewResource"
},
"workflow_run_id": {
"type": "string"
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
}
},
"description": " For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets."
}
POST /api/projects/{project_id}/workers/{id}/redeploy
Redeploy a worker
Starts another Worker::BuildAndDeploy from the last run’s input. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Redeploy a worker",
"description": "Starts another `Worker::BuildAndDeploy` from the last run’s input. For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.",
"operationId": "redeployWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"redeploy": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"existing",
"branch",
"commit"
]
},
"branch": {
"type": "string"
},
"git_sha": {
"type": "string"
}
}
}
}
}
}
}
},
"responses": {
"202": {
"description": "Resource accepted; workflow started. This does not confirm deployment or teardown completion. Poll the resource GET and inspect workflow status until succeeded or failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkerContractMutation"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_git_ref",
"invalid_worker",
"missing_aws_account",
"missing_permissions",
"no_previous_deployment"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
POST /api/projects/{project_id}/workers/{id}/resume
Resume worker
For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets.
{
"tags": [
"Workers"
],
"summary": "Resume worker",
"operationId": "resumeWorker",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_availability_change",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"202": {
"description": "Resource accepted; workflow started. This does not confirm deployment or teardown completion. Poll the resource GET and inspect workflow status until succeeded or failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkerContractMutation"
}
}
}
}
},
"description": " For meaningful deployment decisions, read relevant agent notes first. After approval, use createAgentNote to record intent and link returned resource/workflow IDs; append observed outcomes or failures. Notes never authorize changes and must not contain secrets."
}
GET /api/projects/{project_id}/workers/{id}/tasks
List observed ECS tasks
Returns live task state for the worker service. Includes task ID, status, health, start time, availability zone, capacity provider, task definition revision, private IP, and container status. Does not return task environment values.
{
"tags": [
"Workers"
],
"summary": "List observed ECS tasks",
"description": "Returns live task state for the worker service. Includes task ID, status, health, start time, availability zone, capacity provider, task definition revision, private IP, and container status. Does not return task environment values.",
"operationId": "getWorkerTasks",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WorkerId"
}
],
"responses": {
"200": {
"description": "Observed running-desired ECS tasks. No task environment values. Task fields may be absent when AWS omits them.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"state": {
"type": "string",
"const": "not_ready",
"description": "Present only when no compute workflow has usable service context."
},
"desired_count": {
"type": "integer"
},
"running_count": {
"type": "integer"
},
"pending_count": {
"type": "integer"
},
"tasks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"desired_status": {
"type": "string"
},
"health_status": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"availability_zone": {
"type": "string"
},
"capacity_provider": {
"type": "string"
},
"task_definition": {
"type": "string"
},
"private_ipv4": {
"type": "string"
},
"containers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"health_status": {
"type": "string"
}
}
}
}
}
}
}
},
"required": [
"desired_count",
"running_count",
"pending_count",
"tasks"
]
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthenticated"
},
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"worker_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"aws_credentials_invalid",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
Referenced definitions
These keys resolve the local references in the operations above.{
"#/components/parameters/PreviewId": {
"name": "preview_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
"#/components/parameters/ProjectIdInPath": {
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
"#/components/parameters/WorkerId": {
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
"#/components/responses/InvalidParameters": {
"description": "Missing or malformed JSON parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "invalid_parameters"
}
}
}
},
"#/components/responses/Unauthenticated": {
"description": "No session cookie",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "unauthenticated"
}
}
}
},
"#/components/schemas/ComputePreview": {
"type": "object",
"required": [
"id",
"status"
],
"properties": {
"id": {
"type": "string"
},
"branch": {
"type": [
"string",
"null"
]
},
"git_sha": {
"type": [
"string",
"null"
]
},
"commit_url": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"deploying",
"live",
"failed",
"deleting"
]
},
"public_url": {
"type": [
"string",
"null"
]
},
"alias_url": {
"type": [
"string",
"null"
]
},
"is_alias_head": {
"type": "boolean"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"workflow_run": {
"anyOf": [
{
"$ref": "#/components/schemas/ComputeWorkflowRun"
},
{
"type": "null"
}
]
},
"teardown_run": {
"anyOf": [
{
"$ref": "#/components/schemas/ComputeWorkflowRun"
},
{
"type": "null"
}
]
}
}
},
"#/components/schemas/ComputePreviewResource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"example": "web_server"
},
"status": {
"type": "string"
},
"container_port": {
"type": [
"integer",
"null"
]
},
"health_path": {
"type": [
"string",
"null"
]
},
"vcpu": {
"type": [
"number",
"null"
]
},
"memory_gb": {
"type": [
"number",
"null"
]
},
"min_copies": {
"type": [
"integer",
"null"
]
},
"max_copies": {
"type": [
"integer",
"null"
]
},
"deploy_branch_pattern": {
"type": [
"string",
"null"
]
}
}
},
"#/components/schemas/ComputeWorkflowRun": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"succeeded",
"failed"
]
},
"current_step": {
"type": [
"string",
"null"
]
},
"in_progress": {
"type": "boolean"
},
"repository": {
"type": [
"string",
"null"
]
},
"git_sha": {
"type": [
"string",
"null"
]
},
"commit_url": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"started_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"finished_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"build_started": {
"type": "boolean"
},
"failure_detail": {
"type": [
"string",
"null"
]
},
"failure_code": {
"type": [
"string",
"null"
]
},
"failure_error": {
"type": [
"string",
"null"
]
}
}
},
"#/components/schemas/CostPage": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"example": "USD"
},
"estimated": {
"type": "boolean"
},
"hours": {
"type": "number"
},
"copies": {
"type": "integer"
},
"current_usd": {
"type": "string"
},
"monthly_usd": {
"type": "string"
},
"disclaimer": {
"type": "string"
},
"cost_explorer_url": {
"type": [
"string",
"null"
],
"description": "Cost Explorer console URL filtered by user:springwinter:project_id. Null when the project id is blank. Does not call the Cost Explorer API."
},
"resources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"scope": {
"type": "string"
},
"aws_id": {
"type": [
"string",
"null"
]
},
"detail": {
"type": [
"string",
"null"
]
},
"current_usd": {
"type": "string"
},
"monthly_usd": {
"type": "string"
},
"console_url": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"#/components/schemas/EnvironmentPage": {
"type": "object",
"required": [
"variables"
],
"properties": {
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvironmentVariable"
}
}
}
},
"#/components/schemas/EnvironmentVariable": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"#/components/schemas/Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"#/components/schemas/LogPage": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"build",
"server"
]
},
"workflow_run_id": {
"type": [
"string",
"null"
]
},
"group": {
"type": [
"string",
"null"
]
},
"stream": {
"type": [
"string",
"null"
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"next_token": {
"type": [
"string",
"null"
]
},
"in_progress": {
"type": "boolean"
},
"console_url": {
"type": [
"string",
"null"
],
"description": "CloudWatch Logs Insights console URL for this log group in the project region. Null when group or region is blank. Does not call the Logs Insights API."
}
}
},
"#/components/schemas/MetricsPage": {
"type": "object",
"properties": {
"range": {
"type": "string"
},
"period": {
"type": "integer"
},
"in_progress": {
"type": "boolean"
},
"widgets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"unit": {
"type": "string"
},
"stat": {
"type": "string"
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string"
},
"value": {
"type": [
"number",
"null"
]
}
}
}
}
}
}
}
}
},
"#/components/schemas/WorkerContractMutation": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/WorkerContractResource"
},
"workflow_run_id": {
"type": "string"
}
},
"required": [
"resource",
"workflow_run_id"
]
},
"#/components/schemas/WorkerContractResource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"const": "worker"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"suspended"
]
},
"dockerfile_path": {
"type": [
"string",
"null"
]
},
"root_directory": {
"type": "string",
"default": "."
},
"container_command": {
"type": [
"string",
"null"
]
},
"vcpu": {
"type": [
"number",
"null"
]
},
"memory_gb": {
"type": [
"number",
"null"
]
},
"min_copies": {
"type": [
"integer",
"null"
]
},
"max_copies": {
"type": [
"integer",
"null"
]
},
"deploy_branch_pattern": {
"type": [
"string",
"null"
]
},
"ebs_size_gib": {
"type": [
"integer",
"null"
]
},
"ebs_mount_path": {
"type": [
"string",
"null"
]
},
"spot_mode": {
"type": [
"string",
"null"
],
"enum": [
"on_demand",
"spot_only",
"balanced",
null
]
}
},
"required": [
"id",
"name",
"kind",
"status",
"dockerfile_path",
"root_directory",
"container_command",
"vcpu",
"memory_gb",
"min_copies",
"max_copies",
"deploy_branch_pattern",
"ebs_size_gib",
"ebs_mount_path",
"spot_mode"
]
},
"#/components/schemas/WorkerContractShow": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/WorkerContractResource"
},
"workflow_run": {
"anyOf": [
{
"$ref": "#/components/schemas/ComputeWorkflowRun"
},
{
"type": "null"
}
]
},
"workflow_runs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ComputeWorkflowRun"
}
},
"teardown_run": {
"anyOf": [
{
"$ref": "#/components/schemas/ComputeWorkflowRun"
},
{
"type": "null"
}
]
},
"public_url": {
"type": [
"string",
"null"
]
},
"previews": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ComputePreview"
}
},
"availability_run": {
"anyOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/ComputeWorkflowRun"
},
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"pause",
"resume"
]
}
}
}
]
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run",
"workflow_runs",
"teardown_run",
"public_url",
"previews",
"availability_run"
]
}
}