{
  "openapi": "3.0.3",
  "info": {
    "title": "Polykomos REST API",
    "version": "v1",
    "description": "Provision and manage PostgreSQL and MySQL databases with resource-oriented endpoints and bearer token authentication."
  },
  "servers": [
    {
      "url": "https://polykomos.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pk_live_..."
      }
    },
    "schemas": {
      "Database": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "example": "database"
          },
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "my-app-db"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "provisioning",
              "paused",
              "deleted"
            ]
          },
          "region": {
            "type": "string",
            "example": "us-east-1"
          },
          "plan": {
            "type": "string",
            "example": "free"
          },
          "quotas": {
            "type": "object",
            "properties": {
              "storage_hard_limit_gb": {
                "type": "number",
                "nullable": true
              },
              "connection_hard_limit": {
                "type": "integer",
                "nullable": true
              },
              "warning_threshold_pct": {
                "type": "integer",
                "nullable": true
              }
            }
          },
          "db_type": {
            "type": "string",
            "example": "postgres"
          },
          "host": {
            "type": "string",
            "example": "db-42.polykomos.com"
          },
          "port": {
            "type": "integer",
            "example": 5432
          },
          "db_name": {
            "type": "string",
            "example": "my-app-db"
          },
          "db_username": {
            "type": "string",
            "example": "u42"
          },
          "team_id": {
            "type": "integer",
            "nullable": true,
            "description": "Owning team identifier for this database."
          },
          "team_name": {
            "type": "string",
            "nullable": true,
            "description": "Owning team name for this database."
          },
          "db_password": {
            "type": "string",
            "nullable": true,
            "description": "Only returned on create and single-get endpoints."
          },
          "connection_string": {
            "type": "string",
            "example": "postgresql://u42:***@db-42.polykomos.com:5432/my-app-db"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "example": "webhook_endpoint"
          },
          "id": {
            "type": "integer"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "revoked"
            ]
          },
          "last_success_at": {
            "type": "string",
            "nullable": true
          },
          "last_failure_at": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string"
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "example": "webhook_delivery"
          },
          "id": {
            "type": "integer"
          },
          "endpoint_id": {
            "type": "integer"
          },
          "event_type": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "delivered",
              "failed"
            ]
          },
          "response_code": {
            "type": "integer",
            "nullable": true
          },
          "error_message": {
            "type": "string",
            "nullable": true
          },
          "attempt_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string"
          }
        }
      },
      "Blueprint": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "example": "blueprint"
          },
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "seed-contacts"
          },
          "slug": {
            "type": "string",
            "example": "seed-contacts"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "content_type": {
            "type": "string",
            "example": "sql"
          },
          "version": {
            "type": "integer",
            "example": 1
          },
          "size_bytes": {
            "type": "integer"
          },
          "is_system_blueprint": {
            "type": "boolean"
          },
          "variables": {
            "type": "object",
            "nullable": true
          },
          "metadata": {
            "type": "object",
            "nullable": true
          },
          "sql_content": {
            "type": "string",
            "description": "Full SQL content. Only included on single-get endpoints."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BlueprintApplication": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "example": "blueprint_application"
          },
          "id": {
            "type": "integer"
          },
          "blueprint_id": {
            "type": "integer"
          },
          "blueprint_version": {
            "type": "integer"
          },
          "database_instance_id": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "completed",
              "failed",
              "rolled_back"
            ]
          },
          "is_dry_run": {
            "type": "boolean"
          },
          "execution_log": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "object"
            }
          },
          "total_duration_ms": {
            "type": "integer",
            "nullable": true
          },
          "statements_total": {
            "type": "integer"
          },
          "statements_succeeded": {
            "type": "integer"
          },
          "statements_failed": {
            "type": "integer"
          },
          "error_message": {
            "type": "string",
            "nullable": true
          },
          "variable_values": {
            "type": "object",
            "nullable": true
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "error",
          "request_id"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "missing_required_field"
              },
              "message": {
                "type": "string",
                "example": "Missing required field: name"
              },
              "details": {
                "type": "object"
              }
            }
          },
          "request_id": {
            "type": "string",
            "example": "req_a1b2c3d4e5f6"
          }
        }
      },
      "PaginationParams": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 25
          },
          "starting_after": {
            "type": "string",
            "description": "Cursor: UUID or ID of the last item from the previous page."
          }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "in": "header",
        "name": "Idempotency-Key",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "A unique key for idempotent request handling. Use a UUID."
      },
      "Limit": {
        "in": "query",
        "name": "limit",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        },
        "description": "Number of items to return per page."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid Authorization header",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Invalid key, missing scope, IP blocked, or expired key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit or quota exceeded",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait before retrying"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerApiKey": []
    }
  ],
  "paths": {
    "/api/v1/me": {
      "get": {
        "summary": "Get authenticated user and API key context",
        "operationId": "getMe",
        "tags": [
          "Authentication"
        ],
        "responses": {
          "200": {
            "description": "User and key context",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "user": {
                          "type": "object",
                          "properties": {
                            "object": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "email": {
                              "type": "string"
                            }
                          }
                        },
                        "api_key": {
                          "type": "object",
                          "properties": {
                            "object": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "preview": {
                              "type": "string"
                            },
                            "permissions": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "status": {
                              "type": "string"
                            },
                            "last_used_at": {
                              "type": "string",
                              "nullable": true
                            },
                            "controls": {
                              "type": "object",
                              "properties": {
                                "requests_per_minute": {
                                  "type": "integer"
                                },
                                "monthly_quota": {
                                  "type": "integer",
                                  "nullable": true
                                },
                                "allowed_ip_list": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "inactive_ttl_days": {
                                  "type": "integer",
                                  "nullable": true
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/databases": {
      "get": {
        "summary": "List databases",
        "operationId": "listDatabases",
        "tags": [
          "Databases"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "in": "query",
            "name": "starting_after",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "UUID of the last database from the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of databases",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Database"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "summary": "Create a database",
        "description": "Creates a database. Pass team_id to target a specific team. If team_id is omitted, the caller's primary team is used.",
        "operationId": "createDatabase",
        "tags": [
          "Databases"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "in": "query",
            "name": "wait",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "If true, block for up to timeout seconds waiting for provisioning."
          },
          {
            "in": "query",
            "name": "timeout",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 120,
              "default": 30
            },
            "description": "Max seconds to wait when wait=true."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9\\-]{0,62}$",
                    "example": "my-app-db"
                  },
                  "db_type": {
                    "type": "string",
                    "example": "postgres",
                    "default": "postgres"
                  },
                  "region": {
                    "type": "string",
                    "example": "us-east-1"
                  },
                  "plan": {
                    "type": "string",
                    "enum": [
                      "free",
                      "launch",
                      "grow"
                    ],
                    "default": "free"
                  },
                  "team_id": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Optional target team ID for the new database."
                  },
                  "storage_hard_limit_gb": {
                    "type": "number",
                    "nullable": true
                  },
                  "connection_hard_limit": {
                    "type": "integer",
                    "nullable": true
                  },
                  "warning_threshold_pct": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "nullable": true
                  },
                  "blueprint_uuid": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional UUID of a blueprint to apply after provisioning."
                  },
                  "blueprint_variables": {
                    "type": "object",
                    "description": "Variables to pass to the blueprint.",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Database created (provisioned within timeout or instantly from pool)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Database"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Database creation accepted, still provisioning",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Database"
                    },
                    "provisioning": {
                      "type": "object",
                      "properties": {
                        "completed": {
                          "type": "boolean"
                        },
                        "waited_seconds": {
                          "type": "integer"
                        },
                        "poll_url": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/databases/{uuid}": {
      "get": {
        "summary": "Get a database by UUID",
        "operationId": "getDatabase",
        "tags": [
          "Databases"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Database details with connection credentials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Database"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "summary": "Update a database",
        "operationId": "updateDatabase",
        "tags": [
          "Databases"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9\\-]{0,62}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated database",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Database"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      },
      "delete": {
        "summary": "Delete a database",
        "operationId": "deleteDatabase",
        "tags": [
          "Databases"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Database deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "object": {
                          "type": "string"
                        },
                        "uuid": {
                          "type": "string"
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "cancelled_provision_jobs": {
                          "type": "integer"
                        },
                        "destroy_scheduled_at": {
                          "type": "string",
                          "nullable": true
                        },
                        "has_remote_resources": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/webhook_endpoints": {
      "get": {
        "summary": "List webhook endpoints",
        "operationId": "listWebhookEndpoints",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "in": "query",
            "name": "starting_after",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "ID of the last endpoint from the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of webhook endpoints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "summary": "Create a webhook endpoint",
        "operationId": "createWebhookEndpoint",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://your-app.com/webhooks/polykomos"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Events to subscribe to. Empty array means all events.",
                    "example": [
                      "database.provisioned",
                      "database.deleted"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook endpoint created. Secret is returned once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/WebhookEndpoint"
                    },
                    "secret": {
                      "type": "string",
                      "description": "HMAC signing secret. Shown once."
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/webhook_endpoints/{id}": {
      "delete": {
        "summary": "Revoke a webhook endpoint",
        "operationId": "revokeWebhookEndpoint",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook endpoint revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/webhook_endpoints/{id}/deliveries": {
      "get": {
        "summary": "List webhook delivery attempts",
        "operationId": "listWebhookDeliveries",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "in": "query",
            "name": "starting_after",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "ID of the last delivery from the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of delivery attempts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/blueprints": {
      "get": {
        "summary": "List blueprints",
        "operationId": "listBlueprints",
        "tags": [
          "Blueprints"
        ],
        "description": "Requires scope: blueprints:read.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "in": "query",
            "name": "starting_after",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "UUID of the last blueprint from the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of blueprints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Blueprint"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "summary": "Create a blueprint",
        "operationId": "createBlueprint",
        "tags": [
          "Blueprints"
        ],
        "description": "Requires scope: blueprints:write.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "sql_content"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "sql_content": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "variables": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Blueprint created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Blueprint"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/blueprints/{uuid}": {
      "get": {
        "summary": "Get a blueprint by UUID",
        "operationId": "getBlueprint",
        "tags": [
          "Blueprints"
        ],
        "description": "Requires scope: blueprints:read. Returns the full blueprint including sql_content.",
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Blueprint details with sql_content included",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Blueprint"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "summary": "Update a blueprint",
        "operationId": "updateBlueprint",
        "tags": [
          "Blueprints"
        ],
        "description": "Requires scope: blueprints:write.",
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "sql_content": {
                    "type": "string"
                  },
                  "variables": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated blueprint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Blueprint"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      },
      "delete": {
        "summary": "Delete a blueprint",
        "operationId": "deleteBlueprint",
        "tags": [
          "Blueprints"
        ],
        "description": "Requires scope: blueprints:write.",
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Blueprint deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/database_types": {
      "get": {
        "summary": "List database types",
        "operationId": "getDatabaseTypes",
        "tags": [
          "Databases"
        ],
        "responses": {
          "200": {
            "description": "Available database types with regions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "is_provisionable": {
                            "type": "boolean"
                          },
                          "is_available": {
                            "type": "boolean"
                          },
                          "regions": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "code": {
                                  "type": "string"
                                },
                                "label": {
                                  "type": "string"
                                },
                                "is_available": {
                                  "type": "boolean"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/databases/{uuid}/quotas": {
      "patch": {
        "summary": "Update database quotas",
        "operationId": "updateDatabaseQuotas",
        "tags": [
          "Databases"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "storage_hard_limit_gb": {
                    "type": "number",
                    "nullable": true
                  },
                  "connection_hard_limit": {
                    "type": "integer",
                    "nullable": true
                  },
                  "warning_threshold_pct": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Database quotas updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Database"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/databases/{uuid}/blueprint_applications": {
      "post": {
        "summary": "Create a database blueprint application",
        "operationId": "createDatabaseBlueprintApplication",
        "tags": [
          "Databases"
        ],
        "description": "Requires scopes: databases:write and blueprints:read.",
        "parameters": [
          {
            "in": "path",
            "name": "uuid",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the database to apply the blueprint to."
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "blueprint_uuid"
                ],
                "properties": {
                  "blueprint_uuid": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "variables": {
                    "type": "object"
                  },
                  "dry_run": {
                    "type": "boolean",
                    "default": false
                  },
                  "wait": {
                    "type": "boolean",
                    "default": true
                  },
                  "timeout": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 120,
                    "default": 30
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Blueprint application completed or rolled back",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/BlueprintApplication"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Blueprint application still running",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "$ref": "#/components/schemas/BlueprintApplication"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/query_executions": {
      "post": {
        "summary": "Create a natural language query execution",
        "operationId": "createQueryExecution",
        "tags": [
          "Natural Language Queries"
        ],
        "description": "Requires scope: queries:write. Supported database engines: PostgreSQL and MySQL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "database_uuid",
                  "query"
                ],
                "properties": {
                  "database_uuid": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "query": {
                    "type": "string",
                    "maxLength": 2000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query executed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "sql": {
                      "type": "string",
                      "description": "The generated SQL statement."
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "rows": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          },
                          "description": "Returned for SELECT queries."
                        },
                        "rowCount": {
                          "type": "integer",
                          "description": "Returned for SELECT queries."
                        },
                        "truncated": {
                          "type": "boolean",
                          "description": "True when SELECT results were capped for safety."
                        },
                        "maxRows": {
                          "type": "integer",
                          "description": "Maximum number of SELECT rows returned in one response."
                        },
                        "affectedRows": {
                          "type": "integer",
                          "description": "Returned for INSERT/UPDATE/DELETE queries."
                        },
                        "statementsExecuted": {
                          "type": "integer",
                          "description": "Returned for DDL queries."
                        }
                      }
                    },
                    "query_id": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "description": "Query execution failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "query_execution_failed"
                        },
                        "message": {
                          "type": "string"
                        },
                        "details": {
                          "type": "object",
                          "properties": {
                            "sql": {
                              "type": "string"
                            },
                            "query_id": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/webhook_endpoints/{id}/test_deliveries": {
      "post": {
        "summary": "Create a test webhook delivery",
        "operationId": "createWebhookTestDelivery",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test delivery result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookDelivery"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/blueprint_validations": {
      "post": {
        "summary": "Create a blueprint SQL validation",
        "operationId": "createBlueprintValidation",
        "tags": [
          "Blueprints"
        ],
        "description": "Requires scope: blueprints:read.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sql_content"
                ],
                "properties": {
                  "sql_content": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "valid": {
                          "type": "boolean"
                        },
                        "statement_count": {
                          "type": "integer"
                        },
                        "errors": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "manifest": {
                          "type": "object"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/blueprint_applications/{id}": {
      "get": {
        "summary": "Get a blueprint application",
        "operationId": "getBlueprintApplication",
        "tags": [
          "Blueprints"
        ],
        "description": "Requires scope: blueprints:read.",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "ID of the blueprint application."
          }
        ],
        "responses": {
          "200": {
            "description": "Blueprint application details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BlueprintApplication"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  }
}