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

# SQL databases

> Exact request and response contracts for sql databases.

Generated from the application OpenAPI contract. Do not edit endpoint examples independently.

Read the [agent guide](https://docs.springwinter.dev/api-reference/agents.md) before automating deployments. Fetch the public schema with `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](https://springwinter.dev/docs/api).

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.

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

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

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

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

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

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

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

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

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.