openapi: 3.0.0
info:
  title: Pastebin API
  version: 1.1.0
  description: An API for managing and sharing pastes.
servers:
  - url: https://pastebin.mydomain.com
    description: Production Server
  - url: http://localhost:5000
    description: Local Server
paths:
  /login:
    post:
      summary: User login
      description: Authenticate a user and start a session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
              required:
                - username
                - password
      responses:
        '200':
          description: Login successful
        '401':
          description: Invalid credentials

  /logout:
    get:
      summary: Logout the current user
      description: Logs out the authenticated user.
      responses:
        '200':
          description: User logged out successfully.

  /register:
    post:
      summary: Register a new user
      description: Allows an admin to register a new user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
              required:
                - username
                - password
      responses:
        '201':
          description: User registered successfully
        '400':
          description: Invalid input
        '403':
          description: Unauthorized access
  /paste:
    post:
      summary: Create a new paste
      description: Upload a new paste, either as text or a file. The paste can be private, expire in 1 day, or be permanent.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                c:
                  type: string
                  format: binary
                  description: The content or file to upload
                lang:
                  type: string
                  description: Programming language for syntax highlighting
                expire:
                  type: string
                  enum: [yes, no]
                  default: yes
                  description: >
                    Whether the paste should expire after 1 day.  
                    - `yes` (default): The paste will expire in 24 hours.  
                    - `no`: The paste will be permanent.
                private:
                  type: string
                  enum: [yes, no]
                  default: no
                  description: >
                    Whether the paste should be private.  
                    - `yes`: The paste will only be accessible to the creator and shared users.  
                    - `no` (default): The paste will be public.
      responses:
        '201':
          description: Paste created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: The URL of the created paste
        '400':
          description: Missing content or invalid data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
        '403':
          description: Unauthorized access or user exceeded quota
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message

  /paste/{id}:
    get:
      summary: Retrieve a paste by ID
      description: Fetches the paste content if accessible to the user.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Paste retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  filename:
                    type: string
                  language:
                    type: string
                  content_type:
                    type: string
                  size:
                    type: integer
                  created_at:
                    type: string
                    format: date-time
        '403':
          description: Unauthorized access
        '404':
          description: Paste not found

  /paste/{id}/raw:
    get:
      summary: Get raw paste content
      description: Retrieve the raw content of a paste, either as plain text or binary.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Raw content retrieved successfully
        '404':
          description: Paste not found

  /pastes:
    get:
      summary: List user pastes
      description: Retrieve a list of all pastes created by the authenticated user.
      responses:
        '200':
          description: List of pastes retrieved successfully
        '401':
          description: Unauthorized access

  /stats:
    get:
      summary: Paste Statistics
      description: Returns either an HTML page with visual statistics or JSON data based on the query parameter `format`.
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [html, json]
            default: html
      responses:
        '200':
          description: Statistics response
        '400':
          description: Invalid query parameters

  /user/details:
    get:
      summary: Get current user details
      description: Retrieves the current user's role, storage used, and remaining storage.
      responses:
        '200':
          description: User details retrieved successfully
        '401':
          description: Unauthorized access

  /change-password:
    post:
      summary: Change user password
      description: Allows the authenticated user to change their password.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                current_password:
                  type: string
                new_password:
                  type: string
                confirm_password:
                  type: string
              required:
                - current_password
                - new_password
                - confirm_password
      responses:
        '200':
          description: Password updated successfully
        '400':
          description: Validation errors
        '401':
          description: Unauthorized access or incorrect current password

  /user/{username}/stats:
    get:
      summary: Get user statistics
      description: Retrieve statistics about a user's pastes.
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
        - name: start_date
          in: query
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: User statistics retrieved successfully
        '404':
          description: User not found

  /favorites:
    get:
      summary: List user favorites
      description: Retrieve a list of all favorites for the authenticated user.
      responses:
        '200':
          description: Favorites retrieved successfully
        '401':
          description: Unauthorized access

  /paste/{id}/favorite:
    post:
      summary: Add a paste to favorites
      description: Adds the specified paste to the authenticated user's favorites.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Paste added to favorites
        '404':
          description: Paste not found

  /paste/{id}/unfavorite:
    post:
      summary: Remove a paste from favorites
      description: Removes the specified paste from the authenticated user's favorites.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Paste removed from favorites
        '404':
          description: Paste not in favorites

  /pastes/search:
    get:
      summary: Search pastes
      description: Search for pastes by content, content type, and language.
      security:
        - bearerAuth: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query to match paste content.
        - name: content_type
          in: query
          required: false
          schema:
            type: string
          description: Filter by the MIME type of the paste.
        - name: language
          in: query
          required: false
          schema:
            type: string
          description: Filter by the programming language of the paste.
      responses:
        '200':
          description: Search results retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Unique ID of the paste.
                    title:
                      type: string
                      description: Title of the paste.
                    content:
                      type: string
                      description: Content of the paste (truncated for large pastes).
                    language:
                      type: string
                      description: Programming language of the paste.
                    content_type:
                      type: string
                      description: MIME type of the paste.
                    created_at:
                      type: string
                      format: date-time
                      description: Creation date of the paste.
        '400':
          description: Invalid search query or missing parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Server error while processing the search.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /api/paste/{id}/favorite:
    post:
      summary: Add a paste to favorites from terminal
      description: Marks the specified paste as a favorite for the authenticated user.
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the paste to mark as favorite.
          schema:
            type: integer
      responses:
        '201':
          description: Paste successfully added to favorites.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Paste added to favorites"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Paste already in favorites"
        '401':
          description: Unauthorized
        '404':
          description: Paste not found
        '500':
          description: Server error
  /api/paste/{id}/unfavorite:
    post:
      summary: Remove a paste from favorites from terminal
      description: Removes the specified paste from the authenticated user's favorites.
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the paste to remove from favorites.
          schema:
            type: integer
      responses:
        '200':
          description: Paste successfully removed from favorites.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Paste removed from favorites"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Paste not in favorites"
        '401':
          description: Unauthorized
        '404':
          description: Paste not found
        '500':
          description: Server error
  /api/paste/{id}/download:
    get:
      summary: Download a paste
      description: Downloads the file associated with the specified paste. The server returns the original filename in the `Content-Disposition` header for proper file naming.
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the paste to download.
          schema:
            type: integer
      responses:
        '200':
          description: Successfully downloads the file.
          headers:
            Content-Disposition:
              description: Specifies the filename for the downloaded file.
              schema:
                type: string
                example: attachment; filename="example.txt"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Invalid paste ID"
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "You do not have permission to download this file"
        '404':
          description: Paste not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "File not found"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Unexpected server error"
  /api/favorites:
    get:
      summary: List user favorites
      description: Retrieve a list of all favorites for the authenticated user.
      responses:
        '200':
          description: Favorites retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: Unique ID of the paste
                    url:
                      type: string
                      description: URL of the paste
                    title:
                      type: string
                      description: Title or filename of the paste
                    type:
                      type: string
                      description: Type of the paste
                    size:
                      type: integer
                      description: Size of the paste in bytes
                    created_at:
                      type: string
                      format: date-time
                      description: Creation date of the paste
        '401':
          description: Unauthorized access
        '500':
          description: Error retrieving favorites
  /api/shared_with_others:
    get:
      summary: List pastes shared with others
      description: Retrieve a list of pastes that the authenticated user has shared with others.
      responses:
        '200':
          description: Pastes shared with others retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: Unique ID of the paste.
                    title:
                      type: string
                      description: Title of the paste or filename if title is missing.
                    shared_with:
                      type: array
                      description: List of usernames the paste is shared with.
                      items:
                        type: string
                    can_edit:
                      type: boolean
                      description: Indicates if the shared user can edit the paste.
                    created_at:
                      type: string
                      format: date-time
                      description: Creation date of the paste.
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Authorization token is missing or invalid."
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Unexpected server error."
  /api/shared_with_me:
    get:
      summary: List pastes shared with the user
      description: Retrieve a list of pastes that have been shared with the authenticated user.
      responses:
        '200':
          description: Pastes shared with the user retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: Unique ID of the paste.
                    title:
                      type: string
                      description: Title of the paste or filename if title is missing.
                    owner:
                      type: string
                      description: Username of the owner who shared the paste.
                    can_edit:
                      type: boolean
                      description: Indicates if the user has edit permissions for the paste.
                    created_at:
                      type: string
                      format: date-time
                      description: Creation date of the paste.
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Authorization token is missing or invalid."
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Unexpected server error."
  /api/paste/{id}/unshare:
    post:
      summary: Unshare a paste
      description: Remove the shared permission of a paste for a specific user.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: ID of the paste to unshare.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: The username of the user to unshare the paste with.
              required:
                - username
      responses:
        '200':
          description: Paste successfully unshared.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Paste successfully unshared with username."
        '400':
          description: Invalid request or paste is not shared with the user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Paste is not shared with username."
        '404':
          description: Paste or user not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Paste not found or user not found."
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "An unexpected error occurred."
                  details:
                    type: string
                    example: "Detailed error message."
  /api/paste/{id}:
    put:
      summary: Update existing paste content
      description: Overwrites the content of an existing paste with new data, assuming the user has edit permission.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: ID of the paste to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: The new content for the paste.
              required:
                - content
      responses:
        '200':
          description: Paste updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Paste updated successfully"
        '400':
          description: Missing or invalid content in the request body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Missing 'content' in JSON"
        '403':
          description: The user does not have permission to edit this paste.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "No permission to edit this paste."
        '404':
          description: Paste not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Paste not found"
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "An unexpected error occurred."
                  details:
                    type: string
                    example: "Detailed traceback or error message."
  /api/paste/{id}/share:
    post:
      summary: Share a paste with another user
      description: Share a specific paste with another user, optionally granting them edit permissions.
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the paste to be shared.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Username of the recipient.
                  example: "test_user"
                can_edit:
                  type: boolean
                  description: Indicates whether the recipient can edit the paste.
                  example: true
              required:
                - username
      responses:
        '200':
          description: Paste shared successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Paste shared successfully with test_user."
                  can_edit:
                    type: boolean
                    example: true
        '400':
          description: Bad request, e.g., if the paste is already shared with the user or invalid data is provided.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Paste is already shared with test_user."
        '403':
          description: Forbidden, e.g., if the paste does not belong to the authenticated user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "You do not own this paste."
        '404':
          description: Paste or recipient not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "User test_user not found."
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "An unexpected error occurred."
                  details:
                    type: string
                    example: "Detailed error message for debugging."
  /api/removegps:
    post:
      summary: Remove GPS metadata from an image
      description: Removes GPS metadata from an image file owned by the authenticated user.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paste_id:
                  type: integer
                  description: ID of the paste containing the image.
              required:
                - paste_id
      responses:
        '200':
          description: GPS metadata successfully removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          description: Missing or invalid paste_id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Missing paste_id"
        '403':
          description: User does not have permission to modify this paste.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "You do not have permission to modify this file"
        '404':
          description: Paste or file not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Paste not found"
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Error removing GPS metadata"