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}/storage
Create a private S3 bucket
Checks S3 permissions, creates a managed storage resource, and starts storage-provision. The bucket name is generated. The typed name is a tag. 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": [
"Storage"
],
"summary": "Create a private S3 bucket",
"description": "Checks S3 permissions, creates a managed storage resource, and starts storage-provision. The bucket name is generated. The typed name is a tag. 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": "createStorage",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"storage"
],
"properties": {
"storage": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataStorage"
},
"workflow_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; storage_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"storage_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_storage; name_taken",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_storage",
"name_taken"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
},
"400": {
"description": "invalid_parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_parameters"
]
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/storage/{id}
Show a bucket
{
"tags": [
"Storage"
],
"summary": "Show a bucket",
"operationId": "getStorage",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataStorage"
},
"workflow_run": {
"anyOf": [
{
"$ref": "#/components/schemas/AccountDataWorkflow"
},
{
"type": "null"
}
]
},
"teardown_run": {
"anyOf": [
{
"$ref": "#/components/schemas/AccountDataWorkflow"
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run",
"teardown_run"
]
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; storage_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"storage_not_found"
]
}
},
"required": [
"error"
]
}
}
}
}
}
}
PATCH /api/projects/{project_id}/storage/{id}
Change bucket settings
Versioning, encryption, CORS origins, expire-after days, request metrics, and server access logs. Applies immediately when the bucket is active. 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": [
"Storage"
],
"summary": "Change bucket settings",
"description": "Versioning, encryption, CORS origins, expire-after days, request metrics, and server access logs. Applies immediately when the bucket is active. 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": "updateStorage",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataStorage"
}
},
"required": [
"resource"
]
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; storage_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"storage_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "workflow_in_progress",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_storage; aws_credentials_invalid",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_storage",
"aws_credentials_invalid"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
},
"400": {
"description": "invalid_parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_parameters"
]
}
},
"required": [
"error"
]
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"storage": {
"type": "object",
"properties": {
"versioning": {
"type": "boolean"
},
"encryption": {
"type": "string",
"enum": [
"sse-s3",
"sse-kms"
],
"default": "sse-s3"
},
"kms_key_id": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"cors_origins": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20
},
"expire_days": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 3650
},
{
"type": "null"
}
]
},
"request_metrics": {
"type": "boolean"
},
"audit_logs": {
"type": "boolean"
}
},
"required": []
}
},
"required": [
"storage"
]
}
}
}
}
}
DELETE /api/projects/{project_id}/storage/{id}
Delete a bucket
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": [
"Storage"
],
"summary": "Delete a bucket",
"operationId": "deleteStorage",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataStorage"
},
"workflow_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; storage_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"storage_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "workflow_in_progress",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
}
},
"required": [
"error"
]
}
}
}
},
"400": {
"description": "invalid_parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_parameters"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_storage",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_storage"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"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."
}
PUT /api/projects/{project_id}/storage/{id}
Change bucket settings
Versioning, encryption, CORS origins, expire-after days, request metrics, and server access logs. Applies immediately when the bucket is active. 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": [
"Storage"
],
"summary": "Change bucket settings",
"operationId": "putApiProjectsProjectIdStorageId",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataStorage"
}
},
"required": [
"resource"
]
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; storage_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"storage_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"409": {
"description": "workflow_in_progress",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_storage; aws_credentials_invalid",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_storage",
"aws_credentials_invalid"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
},
"400": {
"description": "invalid_parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_parameters"
]
}
},
"required": [
"error"
]
}
}
}
}
},
"description": "Versioning, encryption, CORS origins, expire-after days, request metrics, and server access logs. Applies immediately when the bucket is active. 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.",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"storage": {
"type": "object",
"properties": {
"versioning": {
"type": "boolean"
},
"encryption": {
"type": "string",
"enum": [
"sse-s3",
"sse-kms"
],
"default": "sse-s3"
},
"kms_key_id": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"cors_origins": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20
},
"expire_days": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 3650
},
{
"type": "null"
}
]
},
"request_metrics": {
"type": "boolean"
},
"audit_logs": {
"type": "boolean"
}
},
"required": []
}
},
"required": [
"storage"
]
}
}
}
}
}
GET /api/projects/{project_id}/storage/{id}/cost
Bucket cost link
Cost Explorer link for the project tag. Billed usage is on the project Cost tab.
{
"tags": [
"Storage"
],
"summary": "Bucket cost link",
"description": "Cost Explorer link for the project tag. Billed usage is on the project Cost tab.",
"operationId": "getStorageCost",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CostPage"
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; storage_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"storage_not_found"
]
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/storage/{id}/metrics
S3 CloudWatch metrics
{
"tags": [
"Storage"
],
"summary": "S3 CloudWatch metrics",
"operationId": "getStorageMetrics",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1d",
"14d"
]
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricsPage"
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; storage_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"storage_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "missing_permissions; aws_credentials_invalid",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"missing_permissions",
"aws_credentials_invalid"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
}
}
}
Referenced definitions
These keys resolve the local references in the operations above.{
"#/components/parameters/ProjectIdInPath": {
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
"#/components/schemas/AccountDataStorage": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"status": {
"type": "string"
},
"bucket_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning": {
"type": "boolean"
},
"encryption": {
"type": "string"
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_origins": {
"type": "array",
"items": {
"type": "string"
}
},
"expire_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"request_metrics": {
"type": "boolean"
},
"audit_logs": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"kind",
"status",
"bucket_name",
"versioning",
"encryption",
"kms_key_id",
"cors_origins",
"expire_days",
"request_metrics",
"audit_logs"
]
},
"#/components/schemas/AccountDataWorkflow": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"in_progress": {
"type": "boolean"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"finished_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"failure_detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"failure_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"failure_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"status",
"current_step",
"in_progress",
"failure_detail",
"failure_code",
"failure_error"
]
},
"#/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/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"
]
}
}
}
}
}
}
}
}
}
}