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}/web_servers
Launch a web server
Checks the customer IAM role with iam:SimulatePrincipalPolicy, creates the Resource, and starts WebServer::BuildAndDeploy. Deployment provisions the Spring Winter hostname and ACM certificate for every project, including those with a custom hostname. 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": [
"Web servers"
],
"summary": "Launch a web server",
"description": "Checks the customer IAM role with `iam:SimulatePrincipalPolicy`, creates the `Resource`, and starts `WebServer::BuildAndDeploy`. Deployment provisions the Spring Winter hostname and ACM certificate for every project, including those with a custom hostname. 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": "createWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"web_server"
],
"properties": {
"web_server": {
"type": "object",
"required": [
"name",
"vcpu",
"memory_gb",
"min_copies",
"max_copies"
],
"properties": {
"name": {
"type": "string"
},
"repository": {
"type": "string",
"example": "acme/api"
},
"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."
},
"port": {
"type": "integer",
"default": 80,
"description": "Container listen port. The ALB stays HTTP :80."
},
"health_path": {
"type": "string",
"default": "/",
"description": "HTTP path the ALB pings. Expects HTTP 200."
},
"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"
},
"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"
}
},
"variables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnvironmentVariable"
},
"description": "Initial runtime environment. Values stay in AWS."
},
"image": {
"type": "string",
"maxLength": 512,
"example": "nginx:1.27",
"description": "Public image with explicit tag or sha256 digest. No URL scheme or whitespace. Choose exactly one nonblank image or repository. Image sources reject nonempty build_variables and have no GitHub previews or auto-deploy."
}
},
"oneOf": [
{
"required": [
"repository",
"dockerfile_path"
],
"properties": {
"repository": {
"type": "string",
"minLength": 1
},
"image": {
"type": [
"string",
"null"
],
"enum": [
"",
null
]
}
}
},
{
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"minLength": 1
},
"repository": {
"type": [
"string",
"null"
],
"enum": [
"",
null
]
}
}
}
]
}
}
}
}
}
},
"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/WebServerContractMutation"
}
}
}
},
"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_web_server",
"missing_aws_account",
"missing_permissions",
"spot_unavailable_for_volume"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
},
"503": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"managed_hostname_unavailable"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/web_servers/{id}
Show a web server
{
"tags": [
"Web servers"
],
"summary": "Show a web server",
"operationId": "getWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"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/WebServerContractShow"
}
}
}
},
"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",
"web_server_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
PATCH /api/projects/{project_id}/web_servers/{id}
Update desired source, compute, health path, or auto-deploy
Writes root_directory, dockerfile_path, port, container_command, vcpu, memory_gb, min_copies, max_copies, spot_mode, health_path, deploy_branch_pattern, and/or ebs_size_gib with ebs_mount_path on the resource. Does not start a workflow. Allowed during deploy; rejected during teardown. 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. port is the container listen port (1–65535). An empty deploy_branch_pattern turns auto-deploy off. A blank health_path stores /. A data volume applies on the next Redeploy. Spot modes are rejected with a data volume and apply on the next Redeploy. Null size and path clear it. Image sources can update image; GitHub sources can update dockerfile_path and root_directory. Source type cannot be changed. service_hostname is also accepted. 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": [
"Web servers"
],
"summary": "Update desired source, compute, health path, or auto-deploy",
"description": "Writes `root_directory`, `dockerfile_path`, `port`, `container_command`, `vcpu`, `memory_gb`, `min_copies`, `max_copies`, `spot_mode`, `health_path`, `deploy_branch_pattern`, and/or `ebs_size_gib` with `ebs_mount_path` on the resource. Does not start a workflow. Allowed during deploy; rejected during teardown. `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. `port` is the container listen port (1–65535). An empty `deploy_branch_pattern` turns auto-deploy off. A blank `health_path` stores `/`. A data volume applies on the next Redeploy. Spot modes are rejected with a data volume and apply on the next Redeploy. Null size and path clear it. Image sources can update image; GitHub sources can update dockerfile_path and root_directory. Source type cannot be changed. service_hostname is also accepted. 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": "updateWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"web_server"
],
"properties": {
"web_server": {
"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."
},
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535,
"description": "Port the process listens on. The load balancer stays on HTTP :80. Applies on the next Redeploy."
},
"health_path": {
"type": "string",
"description": "HTTP path the ALB pings. Expects HTTP 200. Blank stores `/`. Applies on the next Redeploy."
},
"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"
]
},
"image": {
"type": "string",
"maxLength": 512,
"example": "nginx:1.27",
"description": "Change an existing public-image source only. Cannot convert a GitHub resource into an image resource. Applies on Redeploy."
},
"service_hostname": {
"type": [
"string",
"null"
],
"description": "Desired service hostname label. Validation failures return invalid_service_hostname."
}
}
}
}
}
}
}
},
"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/WebServerContractResource"
}
},
"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",
"web_server_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_service_hostname",
"invalid_web_server",
"spot_unavailable_for_volume"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
DELETE /api/projects/{project_id}/web_servers/{id}
Tear down a web server
Starts WebServer::Teardown. The resource is soft-deleted only after AWS destroy succeeds. 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": [
"Web servers"
],
"summary": "Tear down a web server",
"description": "Starts `WebServer::Teardown`. The resource is soft-deleted only after AWS destroy succeeds. 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": "deleteWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"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/WebServerContractMutation"
}
}
}
},
"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",
"web_server_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_web_server",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
PUT /api/projects/{project_id}/web_servers/{id}
Update desired source, compute, health path, or auto-deploy
Writes root_directory, dockerfile_path, port, container_command, vcpu, memory_gb, min_copies, max_copies, spot_mode, health_path, deploy_branch_pattern, and/or ebs_size_gib with ebs_mount_path on the resource. Does not start a workflow. Allowed during deploy; rejected during teardown. 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. port is the container listen port (1–65535). An empty deploy_branch_pattern turns auto-deploy off. A blank health_path stores /. A data volume applies on the next Redeploy. Spot modes are rejected with a data volume and apply on the next Redeploy. Null size and path clear it. Image sources can update image; GitHub sources can update dockerfile_path and root_directory. Source type cannot be changed. service_hostname is also accepted. 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": [
"Web servers"
],
"summary": "Update desired source, compute, health path, or auto-deploy",
"description": "Writes `root_directory`, `dockerfile_path`, `port`, `container_command`, `vcpu`, `memory_gb`, `min_copies`, `max_copies`, `spot_mode`, `health_path`, `deploy_branch_pattern`, and/or `ebs_size_gib` with `ebs_mount_path` on the resource. Does not start a workflow. Allowed during deploy; rejected during teardown. `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. `port` is the container listen port (1–65535). An empty `deploy_branch_pattern` turns auto-deploy off. A blank `health_path` stores `/`. A data volume applies on the next Redeploy. Spot modes are rejected with a data volume and apply on the next Redeploy. Null size and path clear it. Image sources can update image; GitHub sources can update dockerfile_path and root_directory. Source type cannot be changed. service_hostname is also accepted. 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": "replaceWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"web_server"
],
"properties": {
"web_server": {
"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."
},
"port": {
"type": "integer",
"minimum": 1,
"maximum": 65535,
"description": "Port the process listens on. The load balancer stays on HTTP :80. Applies on the next Redeploy."
},
"health_path": {
"type": "string",
"description": "HTTP path the ALB pings. Expects HTTP 200. Blank stores `/`. Applies on the next Redeploy."
},
"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"
]
},
"image": {
"type": "string",
"maxLength": 512,
"example": "nginx:1.27",
"description": "Change an existing public-image source only. Cannot convert a GitHub resource into an image resource. Applies on Redeploy."
},
"service_hostname": {
"type": [
"string",
"null"
],
"description": "Desired service hostname label. Validation failures return invalid_service_hostname."
}
}
}
}
}
}
}
},
"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/WebServerContractResource"
}
},
"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",
"web_server_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_service_hostname",
"invalid_web_server",
"spot_unavailable_for_volume"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/web_servers/{id}/cost
Estimated spend
Catalog on-demand USD for tagged resources Spring Winter created. Not Cost Explorer billed usage and not the AWS invoice. Includes cost_explorer_url, a console deep link filtered by the project tag; customers must activate that cost allocation tag in Billing.
{
"tags": [
"Web servers"
],
"summary": "Estimated spend",
"description": "Catalog on-demand USD for tagged resources Spring Winter created. Not Cost Explorer billed usage and not the AWS invoice. Includes cost_explorer_url, a console deep link filtered by the project tag; customers must activate that cost allocation tag in Billing.",
"operationId": "getWebServerCost",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"responses": {
"200": {
"description": "Cost estimate",
"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",
"web_server_not_found"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/web_servers/{id}/environment
Read ECS 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": [
"Web servers"
],
"summary": "Read ECS environment variables",
"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.",
"operationId": "getWebServerEnvironment",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"name": "scope",
"in": "query",
"schema": {
"type": "string",
"enum": [
"runtime",
"build"
]
}
}
],
"responses": {
"200": {
"description": "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",
"web_server_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"
]
}
}
}
}
}
}
PUT /api/projects/{project_id}/web_servers/{id}/environment
Replace ECS 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": [
"Web servers"
],
"summary": "Replace ECS environment variables",
"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.",
"operationId": "putWebServerEnvironment",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"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",
"web_server_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_web_server",
"missing_aws_account",
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for missing_permissions."
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/web_servers/{id}/logs
Tail CloudWatch logs
CodeBuild or ECS CloudWatch events for this resource. Includes console_url, a CloudWatch Logs Insights deep link for the current source’s log group. Does not call StartQuery.
{
"tags": [
"Web servers"
],
"summary": "Tail CloudWatch logs",
"description": "CodeBuild or ECS CloudWatch events for this resource. Includes console_url, a CloudWatch Logs Insights deep link for the current source’s log group. Does not call StartQuery.",
"operationId": "getWebServerLogs",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"name": "source",
"in": "query",
"schema": {
"type": "string",
"enum": [
"build",
"server"
],
"default": "build"
}
},
{
"name": "run_id",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "next_token",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1h",
"3h",
"12h",
"1d"
],
"default": "1h"
}
},
{
"name": "filter",
"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",
"web_server_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}/web_servers/{id}/metrics
CloudWatch metrics
CPU, memory, running replica count, ALB requests, and target 5xx for the selected range. Does not persist datapoints.
{
"tags": [
"Web servers"
],
"summary": "CloudWatch metrics",
"description": "CPU, memory, running replica count, ALB requests, and target 5xx for the selected range. Does not persist datapoints.",
"operationId": "getWebServerMetrics",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1h",
"3h",
"12h",
"1d"
],
"default": "1h"
}
}
],
"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",
"web_server_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}/web_servers/{id}/pause
Pause web server
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": [
"Web Servers"
],
"summary": "Pause web server",
"operationId": "pauseWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"web_server_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/WebServerContractMutation"
}
}
}
}
},
"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}/web_servers/{id}/previews
Create a preview of a web server
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": [
"Web servers"
],
"summary": "Create a preview of a web server",
"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": "createWebServerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"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": [
"web_server_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}/web_servers/{id}/previews/{preview_id}
Show a web server preview
{
"tags": [
"Web servers"
],
"summary": "Show a web server preview",
"operationId": "getWebServerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"$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}/web_servers/{id}/previews/{preview_id}
Tear down a web server preview
Starts WebServer::Teardown on the child only. Production is unchanged. 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": [
"Web servers"
],
"summary": "Tear down a web server preview",
"description": "Starts `WebServer::Teardown` on the child only. Production is unchanged. 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": "deleteWebServerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"$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"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/web_servers/{id}/previews/{preview_id}/environment
Read preview 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": [
"Web servers"
],
"summary": "Read preview environment variables",
"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.",
"operationId": "getWebServerPreviewEnvironment",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"$ref": "#/components/parameters/PreviewId"
},
{
"name": "scope",
"in": "query",
"schema": {
"type": "string",
"enum": [
"runtime",
"build"
]
}
}
],
"responses": {
"200": {
"description": "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": [
"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"
]
}
}
}
}
}
}
PUT /api/projects/{project_id}/web_servers/{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": [
"Web Servers"
],
"summary": "Update Environment preview",
"operationId": "update_environmentWebServerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"$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}/web_servers/{id}/previews/{preview_id}/logs
Tail CloudWatch logs for a preview
Same LogPage as production logs, including console_url for the child resource’s log group.
{
"tags": [
"Web servers"
],
"summary": "Tail CloudWatch logs for a preview",
"description": "Same LogPage as production logs, including console_url for the child resource’s log group.",
"operationId": "getWebServerPreviewLogs",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"$ref": "#/components/parameters/PreviewId"
},
{
"name": "source",
"in": "query",
"schema": {
"type": "string",
"enum": [
"build",
"server"
],
"default": "build"
}
},
{
"name": "run_id",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "next_token",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1h",
"3h",
"12h",
"1d"
],
"default": "1h"
}
},
{
"name": "filter",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Preview observations",
"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": [
"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"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/web_servers/{id}/previews/{preview_id}/metrics
Read CloudWatch metrics for a preview
{
"tags": [
"Web servers"
],
"summary": "Read CloudWatch metrics for a preview",
"operationId": "getWebServerPreviewMetrics",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"$ref": "#/components/parameters/PreviewId"
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1h",
"3h",
"12h",
"1d"
],
"default": "1h"
}
}
],
"responses": {
"200": {
"description": "Preview observations",
"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": [
"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"
]
}
}
}
}
}
}
POST /api/projects/{project_id}/web_servers/{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": [
"Web Servers"
],
"summary": "Redeploy preview",
"operationId": "redeployWebServerPreview",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
},
{
"$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}/web_servers/{id}/redeploy
Redeploy a web server
Starts another WebServer::BuildAndDeploy from the last run’s input. Compute comes from the resource. existing (default) rebuilds the last stored commit SHA; branch resolves HEAD through GitHub; commit uses the SHA. Public-image resources use the saved image reference and ignore Git ref selection. 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": [
"Web servers"
],
"summary": "Redeploy a web server",
"description": "Starts another `WebServer::BuildAndDeploy` from the last run’s input. Compute comes from the resource. `existing` (default) rebuilds the last stored commit SHA; `branch` resolves HEAD through GitHub; `commit` uses the SHA. Public-image resources use the saved image reference and ignore Git ref selection. 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": "redeployWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"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/WebServerContractMutation"
}
}
}
},
"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",
"web_server_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_web_server",
"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}/web_servers/{id}/resume
Resume web server
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": [
"Web Servers"
],
"summary": "Resume web server",
"operationId": "resumeWebServer",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"responses": {
"404": {
"description": "Request rejected. See error code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"web_server_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/WebServerContractMutation"
}
}
}
}
},
"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}/web_servers/{id}/tasks
List observed ECS tasks
Returns live task state for the 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": [
"Web servers"
],
"summary": "List observed ECS tasks",
"description": "Returns live task state for the 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": "getWebServerTasks",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"$ref": "#/components/parameters/WebServerId"
}
],
"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",
"web_server_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/WebServerId": {
"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/WebServerContractMutation": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/WebServerContractResource"
},
"workflow_run_id": {
"type": "string"
}
},
"required": [
"resource",
"workflow_run_id"
]
},
"#/components/schemas/WebServerContractResource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"const": "web_server"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"suspended"
]
},
"container_port": {
"type": [
"integer",
"null"
]
},
"dockerfile_path": {
"type": [
"string",
"null"
]
},
"root_directory": {
"type": "string",
"default": "."
},
"image": {
"type": [
"string",
"null"
]
},
"container_command": {
"type": [
"string",
"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"
]
},
"ebs_size_gib": {
"type": [
"integer",
"null"
]
},
"ebs_mount_path": {
"type": [
"string",
"null"
]
},
"service_hostname": {
"type": [
"string",
"null"
]
},
"spot_mode": {
"type": [
"string",
"null"
],
"enum": [
"on_demand",
"spot_only",
"balanced",
null
]
}
},
"required": [
"id",
"name",
"kind",
"status",
"container_port",
"dockerfile_path",
"root_directory",
"image",
"container_command",
"health_path",
"vcpu",
"memory_gb",
"min_copies",
"max_copies",
"deploy_branch_pattern",
"ebs_size_gib",
"ebs_mount_path",
"service_hostname",
"spot_mode"
]
},
"#/components/schemas/WebServerContractShow": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/WebServerContractResource"
},
"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"
}
]
},
"public_urls": {
"type": "array",
"description": "Service URLs by hostname. Existing clients can continue using `public_url`.",
"items": {
"type": "object",
"required": [
"kind",
"url"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"managed",
"custom"
]
},
"url": {
"type": "string",
"format": "uri"
}
}
}
}
},
"required": [
"resource",
"workflow_run",
"workflow_runs",
"teardown_run",
"public_url",
"previews",
"availability_run",
"public_urls"
]
}
}