{
  "openapi": "3.1.0",
  "info": {
    "title": "Patron API",
    "description": "An open source Patreon alternative with lower fees designed for creators who publish ongoing sequential content like books, podcasts, and comics.",
    "contact": {
      "name": "Patron Team",
      "email": "support@patron.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Local development server"
    },
    {
      "url": "https://api.patron.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/auth/check-email": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Check if email exists",
        "description": "# Errors\nReturns 404 if email doesn't exist, 204 if it does exist, or 500 for database errors.",
        "operationId": "check_email",
        "requestBody": {
          "description": "Email address to check for registration",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckEmailRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Email exists in the system"
          },
          "404": {
            "description": "Email not found in the system"
          },
          "500": {
            "description": "Database connection failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "DATABASE_ERROR",
                  "error": "Database connection failed"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/forgot-password": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Forgot password",
        "description": "# Errors\nReturns an error if database operations fail or email service fails.",
        "operationId": "forgot_password",
        "requestBody": {
          "description": "Email address for password reset request",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ForgotPasswordRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Password reset email sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForgotPasswordResponse"
                }
              }
            }
          },
          "500": {
            "description": "Password reset service error or email delivery failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "EMAIL_SERVICE_ERROR",
                  "error": "Email service unavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/google": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Google `OAuth` redirect",
        "description": "# Errors\nReturns an error if session operations fail or `OAuth` service configuration is invalid.",
        "operationId": "google_auth_redirect",
        "responses": {
          "302": {
            "description": "Redirect to Google OAuth consent screen"
          },
          "500": {
            "description": "OAuth initialization failed or session storage error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "OAUTH_SESSION_ERROR",
                  "error": "Failed to initialize OAuth session"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/google/callback": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Google `OAuth` callback",
        "description": "# Errors\nReturns an error if `OAuth` state verification fails, token exchange fails, or database operations fail.",
        "operationId": "google_auth_callback",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "description": "Authorization code from Google",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "State parameter for CSRF protection",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to frontend application"
          },
          "400": {
            "description": "Invalid authorization code or state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "OAUTH_INVALID_CODE",
                  "error": "Invalid authorization code"
                }
              }
            }
          },
          "500": {
            "description": "OAuth service error or database connection failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "OAUTH_PROVIDER_ERROR",
                  "error": "OAuth provider connection failed"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "User login",
        "description": "# Errors\nReturns an error if credentials are invalid, email is not verified, or database operations fail.",
        "operationId": "login",
        "requestBody": {
          "description": "User login credentials including email and password",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Login successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid credentials or email not verified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_INVALID_CREDENTIALS",
                  "error": "Invalid email or password"
                }
              }
            }
          },
          "500": {
            "description": "Login service error or database connection failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_SERVICE_ERROR",
                  "error": "Authentication service unavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/logout": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Logout",
        "description": "# Errors\nReturns an error if session operations fail.",
        "operationId": "logout",
        "responses": {
          "200": {
            "description": "Successfully logged out",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogoutResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      }
    },
    "/api/auth/me": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Get current user info",
        "description": "# Errors\nReturns an error if user is not authenticated or serialization fails.",
        "operationId": "get_me",
        "responses": {
          "200": {
            "description": "Current user information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserInfo"
                },
                "example": {
                  "auth_provider": "email",
                  "created_at": "2023-01-01T00:00:00",
                  "email": "user@example.com",
                  "email_verified": true,
                  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
                }
              }
            }
          },
          "401": {
            "description": "User authentication required to access profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_REQUIRED",
                  "error": "Not authenticated"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Auth"
        ],
        "summary": "Update user information",
        "description": "# Errors\nReturns an error if database operations fail or user validation fails.",
        "operationId": "update_user_info",
        "requestBody": {
          "description": "Updated user information",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserInfoRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "User information updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateUserInfoResponse"
                }
              }
            }
          },
          "401": {
            "description": "User authentication required to update profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_REQUIRED",
                  "error": "Not authenticated"
                }
              }
            }
          },
          "500": {
            "description": "Database connection failed or update service error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "DATABASE_ERROR",
                  "error": "Database connection failed"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      }
    },
    "/api/auth/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "User registration",
        "description": "# Errors\nReturns an error if input validation fails, user already exists, or database operations fail.",
        "operationId": "register",
        "requestBody": {
          "description": "User registration data including email and password",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Registration successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or email already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_EMAIL_EXISTS",
                  "error": "Email address already registered"
                }
              }
            }
          },
          "500": {
            "description": "Registration service error or email delivery failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "DATABASE_ERROR",
                  "error": "Database connection failed"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/resend-verification": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Resend verification email",
        "description": "# Errors\nReturns an error if user is already verified, database operations fail, or email service fails.",
        "operationId": "resend_verification_email",
        "responses": {
          "200": {
            "description": "Verification email sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResendVerificationResponse"
                }
              }
            }
          },
          "400": {
            "description": "User email already verified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_EMAIL_ALREADY_VERIFIED",
                  "error": "Email is already verified"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required to resend verification email",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_REQUIRED",
                  "error": "Not authenticated"
                }
              }
            }
          },
          "500": {
            "description": "Email service error or database failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "EMAIL_SERVICE_ERROR",
                  "error": "Email service unavailable"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      }
    },
    "/api/auth/reset-password": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Reset password",
        "description": "# Errors\nReturns an error if token is invalid, password validation fails, or database operations fail.",
        "operationId": "reset_password",
        "requestBody": {
          "description": "Password reset token and new password",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResetPasswordRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Password reset successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResetPasswordResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid token or password",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_INVALID_RESET_TOKEN",
                  "error": "Invalid or expired password reset token"
                }
              }
            }
          },
          "500": {
            "description": "Password update service error or database connection failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "RESET_SERVICE_ERROR",
                  "error": "Password reset service unavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/verify-email": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Email verification",
        "description": "# Errors\nReturns an error if token is invalid, expired, or database operations fail.",
        "operationId": "verify_email",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "description": "Email verification token",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to frontend after verification"
          },
          "400": {
            "description": "Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "AUTH_INVALID_VERIFICATION_TOKEN",
                  "error": "Invalid or expired verification token"
                }
              }
            }
          },
          "500": {
            "description": "Email verification service error or database failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "code": "VERIFICATION_SERVICE_ERROR",
                  "error": "Email verification service unavailable"
                }
              }
            }
          }
        }
      }
    },
    "/api/cdn/files/{file_id}": {
      "get": {
        "tags": [
          "Files"
        ],
        "summary": "Serve file content with user authentication",
        "description": "This endpoint is designed to be used to get file content with proper authentication.\nIt verifies user access to the file and returns the file content with proper cache headers.\nThe file content is streamed directly from S3 to minimize memory usage for large files.\n\n# Errors\nReturns an error if file not found, access denied, or S3 operations fail.",
        "operationId": "serve_file_cdn",
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "description": "UUID of the file to stream via CDN",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Streaming file content with CDN-optimized headers",
            "content": {
              "application/octet-stream": {
                "example": "Binary file content with appropriate Content-Type and Cache-Control headers"
              }
            }
          },
          "401": {
            "description": "Authentication required for CDN file access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "CDN access forbidden - user cannot access this file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "CDN file not found or access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "CDN streaming error from storage backend",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      }
    },
    "/api/files": {
      "get": {
        "tags": [
          "Files"
        ],
        "summary": "List user's files with cursor-based pagination",
        "description": "# Errors\nReturns an error if database operations fail.",
        "operationId": "list_files",
        "parameters": [
          {
            "name": "offset",
            "in": "query",
            "description": "UUID offset for cursor-based pagination",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of files to return (default: 50, max: 100)",
            "required": false,
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User files retrieved with pagination support",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserFilesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required to access files",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Database error while retrieving user files",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      }
    },
    "/api/files/actions/upload": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "Upload a file",
        "description": "# Errors\nReturns an error if file upload, database operations, or file system operations fail.",
        "operationId": "upload_file",
        "requestBody": {
          "description": "Multipart form data with file field",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FileUploadRequest"
              },
              "example": {
                "file": "Binary file content - upload any file type (PDF, image, document, etc.)"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "File uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid file upload request or malformed file data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required for file upload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Uploaded file exceeds maximum size limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error during file upload or storage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      }
    },
    "/api/files/{file_id}": {
      "get": {
        "tags": [
          "Files"
        ],
        "summary": "Get a specific file by ID",
        "description": "# Errors\nReturns an error if database operations fail or file not found.",
        "operationId": "get_file",
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "description": "UUID of the file to retrieve details for",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File details retrieved with download URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserFileInfo"
                }
              }
            }
          },
          "401": {
            "description": "User authentication required to view file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "File access denied - user does not own this file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Requested file does not exist or was deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error generating file download URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Files"
        ],
        "summary": "Update file metadata and properties",
        "description": "# Errors\nReturns an error if validation fails, file not found, or database operations fail.",
        "operationId": "update_file",
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "description": "UUID of the file to update metadata for",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "Updated file metadata, filename, or status",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserFileRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "File metadata updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserFileInfo"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required to modify files",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied - cannot modify file owned by another user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Target file not found for update",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Database error while updating file information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Files"
        ],
        "summary": "Permanently delete a user file",
        "description": "# Errors\nReturns an error if file not found, permission denied, or storage operations fail.",
        "operationId": "delete_file",
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "description": "UUID of the file to permanently delete",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "File permanently deleted from storage and database"
          },
          "401": {
            "description": "User authentication needed for file deletion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Delete operation forbidden - file belongs to another user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "File to delete not found or already removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Storage system error during file deletion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "cookieAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AuthProvider": {
        "type": "string",
        "description": "Authentication provider types supported by the system",
        "enum": [
          "google",
          "email",
          "both"
        ]
      },
      "CheckEmailRequest": {
        "type": "object",
        "description": "Request body for checking if email exists",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "Email address to check",
            "example": "user@example.com"
          }
        },
        "example": {
          "email": "user@example.com"
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard JSON error response structure for API endpoints.",
        "required": [
          "error"
        ],
        "properties": {
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional error code for programmatic handling",
            "example": "AUTH_INVALID_CREDENTIALS"
          },
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong",
            "example": "Invalid email or password"
          }
        },
        "example": {
          "code": "AUTH_INVALID_CREDENTIALS",
          "error": "Invalid email or password"
        }
      },
      "FileStatus": {
        "type": "string",
        "description": "File processing status for user uploaded files",
        "enum": [
          "uploaded",
          "processing",
          "processed",
          "failed",
          "deleted"
        ]
      },
      "FileUploadRequest": {
        "type": "object",
        "description": "File upload request schema for multipart form data",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "description": "The file to upload",
            "example": "Binary file content (PDF, image, document, etc.)"
          }
        }
      },
      "FileUploadResponse": {
        "type": "object",
        "description": "Response for file upload operations",
        "required": [
          "message",
          "file"
        ],
        "properties": {
          "file": {
            "$ref": "#/components/schemas/UserFileInfo",
            "description": "Uploaded file information"
          },
          "message": {
            "type": "string",
            "description": "Upload confirmation message"
          }
        },
        "example": {
          "file": {
            "created_at": "2023-01-01T00:00:00Z",
            "file_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "file_size": 1048576,
            "filename": "document.pdf",
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
            "metadata": {
              "description": "Important document"
            },
            "mime_type": "application/pdf",
            "original_filename": "My Important Document.pdf",
            "status": "uploaded",
            "updated_at": "2023-01-01T00:00:00Z",
            "user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          },
          "message": "File uploaded successfully"
        }
      },
      "ForgotPasswordRequest": {
        "type": "object",
        "description": "Request body for password reset",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "Email address to send password reset link to",
            "example": "user@example.com"
          }
        },
        "example": {
          "email": "user@example.com"
        }
      },
      "ForgotPasswordResponse": {
        "type": "object",
        "description": "Response for password reset request",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Password reset request status message"
          }
        },
        "example": {
          "message": "If the email exists in our system, a password reset link has been sent."
        }
      },
      "LoginRequest": {
        "type": "object",
        "description": "Request body for user login",
        "required": [
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "Email address for login authentication"
          },
          "password": {
            "type": "string",
            "description": "User's password"
          }
        },
        "example": {
          "email": "user@example.com",
          "password": "password123"
        }
      },
      "LoginResponse": {
        "type": "object",
        "description": "Response for successful user login",
        "required": [
          "message",
          "user"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Login success message"
          },
          "user": {
            "$ref": "#/components/schemas/UserInfo",
            "description": "User information"
          }
        },
        "example": {
          "message": "Login successful",
          "user": {
            "auth_provider": "email",
            "display_name": "John Doe",
            "email": "user@example.com",
            "email_verified": true,
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
          }
        }
      },
      "LogoutResponse": {
        "type": "object",
        "description": "Response for successful logout",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Logout confirmation message"
          }
        },
        "example": {
          "message": "Logged out successfully"
        }
      },
      "RegisterRequest": {
        "type": "object",
        "description": "Request body for user registration.",
        "required": [
          "email",
          "password"
        ],
        "properties": {
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional display name for the user"
          },
          "email": {
            "type": "string",
            "description": "Email address for new user registration"
          },
          "password": {
            "type": "string",
            "description": "User's password (minimum 8 characters)"
          }
        },
        "example": {
          "email": "user@example.com",
          "password": "password123"
        }
      },
      "RegisterResponse": {
        "type": "object",
        "description": "Response for successful user registration",
        "required": [
          "message",
          "user"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Registration confirmation message"
          },
          "user": {
            "$ref": "#/components/schemas/UserInfo",
            "description": "User information"
          }
        },
        "example": {
          "message": "Registration successful. Please check your email for verification.",
          "user": {
            "auth_provider": "email",
            "display_name": "John Doe",
            "email": "user@example.com",
            "email_verified": false,
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
          }
        }
      },
      "ResendVerificationResponse": {
        "type": "object",
        "description": "Response for resend verification email request",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Resend verification email status message"
          }
        },
        "example": {
          "message": "Verification email sent successfully"
        }
      },
      "ResetPasswordRequest": {
        "type": "object",
        "description": "Request body for password reset confirmation",
        "required": [
          "token",
          "user_id",
          "new_password"
        ],
        "properties": {
          "new_password": {
            "type": "string",
            "description": "New password (minimum 8 characters)"
          },
          "token": {
            "type": "string",
            "description": "Password reset token"
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "description": "User ID associated with the reset token"
          }
        },
        "example": {
          "new_password": "newpassword123",
          "token": "550e8400-e29b-41d4-a716-446655440000",
          "user_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
        }
      },
      "ResetPasswordResponse": {
        "type": "object",
        "description": "Response for successful password reset",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Password reset confirmation message"
          }
        },
        "example": {
          "message": "Password has been reset successfully"
        }
      },
      "UpdateUserFileRequest": {
        "type": "object",
        "description": "Request payload for updating user file metadata, filename, or status",
        "properties": {
          "filename": {
            "type": [
              "string",
              "null"
            ],
            "description": "New filename (optional)",
            "example": "renamed_document.pdf"
          },
          "metadata": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Value",
                "description": "Updated metadata (optional)"
              }
            ]
          },
          "status": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/FileStatus",
                "description": "New status (optional)"
              }
            ]
          }
        },
        "example": {
          "filename": "renamed_document.pdf",
          "metadata": {
            "processed_at": "2023-01-01T12:00:00Z"
          },
          "status": "processed"
        }
      },
      "UpdateUserInfoRequest": {
        "type": "object",
        "description": "Request body for updating user information",
        "properties": {
          "avatar_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Updated avatar URL for the user"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Updated description for the user"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Updated display name for the user"
          }
        },
        "example": {
          "avatar_url": "https://example.com/new-avatar.jpg",
          "description": "A brief description about myself",
          "display_name": "New Display Name"
        }
      },
      "UpdateUserInfoResponse": {
        "type": "object",
        "description": "Response for successful user information update",
        "required": [
          "message",
          "user"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Update confirmation message"
          },
          "user": {
            "$ref": "#/components/schemas/UserInfo",
            "description": "Updated user information"
          }
        },
        "example": {
          "message": "User information updated successfully",
          "user": {
            "auth_provider": "email",
            "display_name": "New Display Name",
            "email": "user@example.com",
            "email_verified": true,
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
          }
        }
      },
      "UserFileInfo": {
        "type": "object",
        "description": "User file information for API responses",
        "required": [
          "id",
          "user_id",
          "filename",
          "original_filename",
          "file_size",
          "mime_type",
          "file_hash",
          "status"
        ],
        "properties": {
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "File upload timestamp",
            "example": "2023-01-01T00:00:00Z"
          },
          "file_hash": {
            "type": "string",
            "description": "SHA-256 hash of the file",
            "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
          },
          "file_size": {
            "type": "integer",
            "format": "int64",
            "description": "Size of the file in bytes",
            "example": 1048576
          },
          "filename": {
            "type": "string",
            "description": "Current filename",
            "example": "document.pdf"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "File's unique identifier",
            "example": "d290f1ee-6c54-4b01-90e6-d701748f0851"
          },
          "metadata": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Value",
                "description": "Additional file metadata"
              }
            ]
          },
          "mime_type": {
            "type": "string",
            "description": "MIME type of the file",
            "example": "application/pdf"
          },
          "original_filename": {
            "type": "string",
            "description": "Original filename as uploaded by user",
            "example": "My Important Document.pdf"
          },
          "status": {
            "$ref": "#/components/schemas/FileStatus",
            "description": "Current processing status"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "File last update timestamp",
            "example": "2023-01-01T00:00:00Z"
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the user who owns this file",
            "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          }
        },
        "example": {
          "created_at": "2023-01-01T00:00:00Z",
          "file_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
          "file_size": 1048576,
          "filename": "document.pdf",
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "metadata": {
            "height": 1080,
            "width": 1920
          },
          "mime_type": "application/pdf",
          "original_filename": "My Important Document.pdf",
          "status": "uploaded",
          "updated_at": "2023-01-01T00:00:00Z",
          "user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        }
      },
      "UserFilesResponse": {
        "type": "array",
        "title": "UserFilesResponse",
        "items": {
          "$ref": "#/components/schemas/UserFileInfo"
        },
        "description": "Collection of user files with metadata",
        "example": [
          {
            "created_at": "2023-01-01T00:00:00Z",
            "file_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "file_size": 1048576,
            "filename": "document.pdf",
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
            "metadata": {
              "description": "Important document"
            },
            "mime_type": "application/pdf",
            "original_filename": "My Important Document.pdf",
            "status": "uploaded",
            "updated_at": "2023-01-01T00:00:00Z",
            "user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          }
        ]
      },
      "UserInfo": {
        "type": "object",
        "description": "User information for API responses and internal use",
        "required": [
          "id",
          "email",
          "auth_provider",
          "email_verified"
        ],
        "properties": {
          "auth_provider": {
            "$ref": "#/components/schemas/AuthProvider",
            "description": "Authentication provider used by the user"
          },
          "avatar_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "URL to user's avatar image",
            "example": "https://example.com/avatar.jpg"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "User account creation timestamp",
            "example": "2023-01-01T00:00:00Z"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "User's display name",
            "example": "John Doe"
          },
          "email": {
            "type": "string",
            "description": "User's registered email address",
            "example": "user@example.com"
          },
          "email_verified": {
            "type": "boolean",
            "description": "Whether the user's email has been verified",
            "example": true
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "User's unique identifier",
            "example": "d290f1ee-6c54-4b01-90e6-d701748f0851"
          },
          "last_login": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Timestamp of user's last login",
            "example": "2023-01-02T12:00:00Z"
          }
        },
        "example": {
          "auth_provider": "email",
          "avatar_url": "https://example.com/avatar.jpg",
          "created_at": "2023-01-01T00:00:00",
          "display_name": "John Doe",
          "email": "user@example.com",
          "email_verified": true,
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "last_login": "2023-01-02T12:00:00"
        }
      },
      "Value": {
        "type": "object",
        "title": "JSONValue",
        "description": "Flexible JSON value that can be an object, array, string, number, boolean, or null"
      }
    },
    "securitySchemes": {
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "sessionid",
        "description": "Session-based authentication using secure HTTP-only cookies"
      }
    }
  },
  "tags": [
    {
      "name": "Auth",
      "description": "Authentication and authorization endpoints"
    },
    {
      "name": "Files",
      "description": "File upload, download, and management endpoints"
    }
  ]
}