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}/sql
Create an RDS or Aurora database
Private encrypted PostgreSQL or MySQL. Standard RDS passwords stay only in customer Secrets Manager. Rotation is not automatic. Missing family selects Aurora for compatibility. 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": [
"SQL"
],
"summary": "Create an RDS or Aurora database",
"description": "Private encrypted PostgreSQL or MySQL. Standard RDS passwords stay only in customer Secrets Manager. Rotation is not automatic. Missing family selects Aurora for compatibility. 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"
}
],
"responses": {
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; sql_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"sql_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_sql; name_taken",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_sql",
"name_taken"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
},
"201": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataSql"
},
"workflow_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
},
"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",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"family": {
"type": "string",
"enum": [
"aurora",
"rds"
],
"default": "aurora"
},
"engine": {
"type": "string",
"enum": [
"postgres",
"mysql"
]
},
"engine_version": {
"type": "string"
},
"database_name": {
"type": "string",
"pattern": "^[A-Za-z][A-Za-z0-9]{0,62}$"
},
"username": {
"type": "string",
"default": "app",
"pattern": "^[A-Za-z][A-Za-z0-9]{0,15}$"
},
"compute_mode": {
"type": "string",
"enum": [
"serverless",
"provisioned"
]
},
"instance_class": {
"type": "string"
},
"retention_days": {
"type": "integer",
"minimum": 1,
"maximum": 35,
"default": 7
},
"min_acu": {
"type": "number",
"minimum": 0.5,
"default": 0.5,
"multipleOf": 0.5
},
"max_acu": {
"type": "number",
"minimum": 0.5,
"default": 4,
"multipleOf": 0.5
},
"allocated_storage": {
"type": "integer",
"minimum": 20
},
"max_allocated_storage": {
"type": "integer",
"minimum": 0,
"description": "0 disables autoscaling. A positive ceiling must be at least 10% above allocated storage."
},
"storage_type": {
"type": "string",
"enum": [
"gp3",
"io1",
"io2"
]
},
"iops": {
"type": "integer"
},
"storage_throughput": {
"type": "integer"
},
"multi_az": {
"type": "boolean"
}
},
"required": [
"name",
"engine",
"engine_version",
"database_name"
],
"additionalProperties": false
}
}
}
}
}
}
}
GET /api/projects/{project_id}/sql/engines
Discover regional SQL configurations
Returns family, engine version, instance class, storage limits, serverless capacity limits, and Multi-AZ support. Revalidate on submission.
{
"tags": [
"SQL"
],
"summary": "Discover regional SQL configurations",
"description": "Returns family, engine version, instance class, storage limits, serverless capacity limits, and Multi-AZ support. Revalidate on submission.",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"engines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"family": {
"type": "string"
},
"engine": {
"type": "string"
},
"engine_version": {
"type": "string"
},
"instance_class": {
"type": "string"
},
"storage_type": {
"type": "string"
},
"min_storage": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"max_storage": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"min_iops": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"max_iops": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"min_acu": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"max_acu": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"supports_storage_autoscaling": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"multi_az_capable": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": [
"family",
"engine",
"engine_version",
"instance_class",
"storage_type",
"min_storage",
"max_storage",
"min_iops",
"max_iops",
"min_acu",
"max_acu",
"supports_storage_autoscaling",
"multi_az_capable"
]
}
}
},
"required": [
"engines"
]
}
}
}
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "Project or SQL resource not found"
},
"422": {
"description": "missing_permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"missing_permissions"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/sql/{id}
Read SQL configuration and workflow history
Includes observed nodes, writer and reader endpoints, desired configuration, pending changes, and workflow history. Passwords are excluded.
{
"tags": [
"SQL"
],
"summary": "Read SQL configuration and workflow history",
"description": "Includes observed nodes, writer and reader endpoints, desired configuration, pending changes, and workflow history. Passwords are excluded.",
"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/AccountDataSql"
},
"workflow_run": {
"anyOf": [
{
"$ref": "#/components/schemas/AccountDataWorkflow"
},
{
"type": "null"
}
]
},
"teardown_run": {
"anyOf": [
{
"$ref": "#/components/schemas/AccountDataWorkflow"
},
{
"type": "null"
}
]
},
"workflow_runs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountDataWorkflow"
}
}
},
"required": [
"resource",
"workflow_run",
"teardown_run",
"workflow_runs"
]
}
}
}
},
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; sql_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"sql_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Invalid SQL configuration or missing AWS permissions"
}
}
}
PATCH /api/projects/{project_id}/sql/{id}
Start a database change
Review with preview_change first. Compute conversion applies within Aurora only. Reader endpoints require application read routing. Scheduled changes remain pending until AWS applies them. 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": [
"SQL"
],
"summary": "Start a database change",
"description": "Review with preview_change first. Compute conversion applies within Aurora only. Reader endpoints require application read routing. Scheduled changes remain pending until AWS applies them. 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"
}
}
],
"responses": {
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; sql_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"sql_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_sql; aws_credentials_invalid",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_sql",
"aws_credentials_invalid"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
},
"202": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataSql"
},
"workflow_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
},
"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"
]
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "object",
"properties": {
"compute_mode": {
"type": "string",
"enum": [
"serverless",
"provisioned"
]
},
"instance_class": {
"type": "string"
},
"retention_days": {
"type": "integer",
"minimum": 1,
"maximum": 35
},
"min_acu": {
"type": "number",
"minimum": 0.5
},
"max_acu": {
"type": "number",
"minimum": 0.5
},
"allocated_storage": {
"type": "integer",
"minimum": 20
},
"max_allocated_storage": {
"type": "integer",
"minimum": 0,
"description": "0 disables autoscaling. A positive ceiling must be at least 10% above allocated storage."
},
"storage_type": {
"type": "string",
"enum": [
"gp3",
"io1",
"io2"
]
},
"iops": {
"type": "integer"
},
"storage_throughput": {
"type": "integer"
},
"multi_az": {
"type": "boolean"
},
"performance_insights_enabled": {
"type": "boolean"
},
"action": {
"type": "string",
"enum": [
"modify",
"add_reader",
"resize_reader",
"remove_reader",
"convert_compute"
],
"default": "modify"
},
"node_id": {
"type": "string"
},
"apply_immediately": {
"type": "boolean",
"default": true
}
},
"required": [],
"additionalProperties": false
}
}
}
}
}
}
}
DELETE /api/projects/{project_id}/sql/{id}
Delete database and readers
Readers are deleted first. Default keeps a final snapshot. RDS retains its credential secret with the snapshot. 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": [
"SQL"
],
"summary": "Delete database and readers",
"description": "Readers are deleted first. Default keeps a final snapshot. RDS retains its credential secret with the snapshot. 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"
}
},
{
"name": "delete_backup",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; sql_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"sql_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_sql",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_sql"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
},
"202": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataSql"
},
"workflow_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
},
"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"
]
}
}
}
}
}
}
PUT /api/projects/{project_id}/sql/{id}
Start a database change
Review with preview_change first. Compute conversion applies within Aurora only. Reader endpoints require application read routing. Scheduled changes remain pending until AWS applies them. 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": [
"SQL"
],
"summary": "Start a database change",
"operationId": "putApiProjectsProjectIdSqlId",
"responses": {
"401": {
"description": "unauthenticated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"unauthenticated"
]
}
},
"required": [
"error"
]
}
}
}
},
"404": {
"description": "project_not_found; sql_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"sql_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "invalid_csrf_token; missing_aws_account; missing_permissions; invalid_sql; aws_credentials_invalid",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_csrf_token",
"missing_aws_account",
"missing_permissions",
"invalid_sql",
"aws_credentials_invalid"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
},
"202": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resource": {
"$ref": "#/components/schemas/AccountDataSql"
},
"workflow_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"resource",
"workflow_run_id"
]
}
}
}
},
"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"
]
}
}
}
}
},
"description": "Review with preview_change first. Compute conversion applies within Aurora only. Reader endpoints require application read routing. Scheduled changes remain pending until AWS applies them. 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",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "object",
"properties": {
"compute_mode": {
"type": "string",
"enum": [
"serverless",
"provisioned"
]
},
"instance_class": {
"type": "string"
},
"retention_days": {
"type": "integer",
"minimum": 1,
"maximum": 35
},
"min_acu": {
"type": "number",
"minimum": 0.5
},
"max_acu": {
"type": "number",
"minimum": 0.5
},
"allocated_storage": {
"type": "integer",
"minimum": 20
},
"max_allocated_storage": {
"type": "integer",
"minimum": 0,
"description": "0 disables autoscaling. A positive ceiling must be at least 10% above allocated storage."
},
"storage_type": {
"type": "string",
"enum": [
"gp3",
"io1",
"io2"
]
},
"iops": {
"type": "integer"
},
"storage_throughput": {
"type": "integer"
},
"multi_az": {
"type": "boolean"
},
"performance_insights_enabled": {
"type": "boolean"
},
"action": {
"type": "string",
"enum": [
"modify",
"add_reader",
"resize_reader",
"remove_reader",
"convert_compute"
],
"default": "modify"
},
"node_id": {
"type": "string"
},
"apply_immediately": {
"type": "boolean",
"default": true
}
},
"required": [],
"additionalProperties": false
}
}
}
}
}
}
}
GET /api/projects/{project_id}/sql/{id}/cost
Read tagged billed SQL cost
Trailing 30-day cost from project Cost Explorer. Includes nodes tagged with this SQL resource ID.
{
"tags": [
"SQL"
],
"summary": "Read tagged billed SQL cost",
"description": "Trailing 30-day cost from project Cost Explorer. Includes nodes tagged with this SQL resource ID.",
"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; sql_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"sql_not_found"
]
}
},
"required": [
"error"
]
}
}
}
},
"422": {
"description": "Invalid SQL configuration or missing AWS permissions"
}
}
}
GET /api/projects/{project_id}/sql/{id}/credentials
Fetch credentials on demand
Returns username, password, host, and port from the customer-account secret. node_id must identify an available node of this resource.
{
"tags": [
"SQL"
],
"summary": "Fetch credentials on demand",
"description": "Returns username, password, host, and port from the customer-account secret. node_id must identify an available node of this resource.",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "node_id",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"password": {
"type": "string"
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
},
"required": [
"username",
"password",
"host",
"port"
]
}
}
}
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "Project or SQL resource not found"
},
"422": {
"description": "missing_aws_account; missing_permissions; aws_credentials_invalid; invalid_sql",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"missing_aws_account",
"missing_permissions",
"aws_credentials_invalid",
"invalid_sql"
]
},
"actions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"error"
]
}
}
}
}
}
}
GET /api/projects/{project_id}/sql/{id}/metrics
Read per-node CloudWatch metrics
{
"tags": [
"SQL"
],
"summary": "Read per-node CloudWatch metrics",
"description": "",
"parameters": [
{
"$ref": "#/components/parameters/ProjectIdInPath"
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1h",
"1d"
]
}
}
],
"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; sql_not_found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"project_not_found",
"sql_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"
]
}
}
}
}
}
}
POST /api/projects/{project_id}/sql/{id}/preview_change
Preview a database change
Read-only AWS validation. Returns changed fields, interruption risk, endpoint effects, and irreversible storage growth. This request does not reserve or apply the change. 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": [
"SQL"
],
"summary": "Preview a database change",
"description": "Read-only AWS validation. Returns changed fields, interruption risk, endpoint effects, and irreversible storage growth. This request does not reserve or apply the change. 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"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string"
},
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"from": {},
"to": {}
},
"required": [
"field",
"from",
"to"
]
}
},
"interruption_possible": {
"type": "boolean"
},
"endpoint_change": {
"type": "boolean"
},
"storage_cannot_shrink": {
"type": "boolean"
},
"read_routing_required": {
"type": "boolean"
},
"node_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"apply_immediately": {
"type": "boolean"
}
},
"required": [
"action",
"changes",
"interruption_possible",
"endpoint_change",
"storage_cannot_shrink",
"read_routing_required",
"node_id",
"apply_immediately"
]
}
}
}
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "Project or SQL resource not found"
},
"422": {
"description": "missing_permissions; aws_credentials_invalid; invalid_sql; invalid_csrf_token",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"missing_permissions",
"aws_credentials_invalid",
"invalid_sql",
"invalid_csrf_token"
]
},
"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"
]
}
}
}
},
"409": {
"description": "workflow_in_progress",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"workflow_in_progress"
]
}
},
"required": [
"error"
]
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "object",
"properties": {
"compute_mode": {
"type": "string",
"enum": [
"serverless",
"provisioned"
]
},
"instance_class": {
"type": "string"
},
"retention_days": {
"type": "integer",
"minimum": 1,
"maximum": 35
},
"min_acu": {
"type": "number",
"minimum": 0.5
},
"max_acu": {
"type": "number",
"minimum": 0.5
},
"allocated_storage": {
"type": "integer",
"minimum": 20
},
"max_allocated_storage": {
"type": "integer",
"minimum": 0,
"description": "0 disables autoscaling. A positive ceiling must be at least 10% above allocated storage."
},
"storage_type": {
"type": "string",
"enum": [
"gp3",
"io1",
"io2"
]
},
"iops": {
"type": "integer"
},
"storage_throughput": {
"type": "integer"
},
"multi_az": {
"type": "boolean"
},
"performance_insights_enabled": {
"type": "boolean"
},
"action": {
"type": "string",
"enum": [
"modify",
"add_reader",
"resize_reader",
"remove_reader",
"convert_compute"
],
"default": "modify"
},
"node_id": {
"type": "string"
},
"apply_immediately": {
"type": "boolean",
"default": true
}
},
"required": [],
"additionalProperties": false
}
}
}
}
}
}
}
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/AccountDataSql": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"kind": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"engine": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"engine_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"database_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"secret_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"family": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"compute_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"instance_class": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"storage_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"change_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reader_host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"writer",
"reader"
]
},
"instance_class": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"availability_zone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"pending_changes": {
"type": "object"
}
},
"required": [
"id",
"role",
"instance_class",
"availability_zone",
"status",
"host",
"pending_changes"
]
}
},
"retention_days": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"min_acu": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"max_acu": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"allocated_storage": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"max_allocated_storage": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"iops": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"storage_throughput": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"performance_insights_enabled": {
"type": "boolean"
},
"multi_az": {
"type": "boolean"
},
"observed": {
"type": "object"
},
"desired": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"pending_changes": {
"type": "object"
}
},
"required": [
"id",
"name",
"kind",
"status",
"engine",
"engine_version",
"database_name",
"username",
"host",
"secret_name",
"family",
"compute_mode",
"instance_class",
"storage_type",
"change_state",
"reader_host",
"nodes",
"retention_days",
"min_acu",
"max_acu",
"port",
"allocated_storage",
"max_allocated_storage",
"iops",
"storage_throughput",
"performance_insights_enabled",
"multi_az",
"observed",
"desired",
"pending_changes"
]
},
"#/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"
]
}
}
}
}
}
}
}
}
}
}