History_Api/docs/swagger.yaml

basePath: /
definitions:
  history-api_internal_dtos_request.ChangePasswordDto:
    properties:
      new_password:
        maxLength: 64
        minLength: 8
        type: string
      old_password:
        maxLength: 64
        minLength: 8
        type: string
    required:
    - new_password
    - old_password
    type: object
  history-api_internal_dtos_request.ChangeRoleDto:
    properties:
      role_ids:
        items:
          type: string
        minItems: 1
        type: array
      user_id:
        type: string
    required:
    - role_ids
    - user_id
    type: object
  history-api_internal_dtos_request.CreateTokenDto:
    properties:
      email:
        type: string
      token_type:
        allOf:
        - $ref: '#/definitions/history-api_pkg_constants.TokenType'
        enum:
        - 1
        - 2
        - 3
        - 4
    required:
    - email
    - token_type
    type: object
  history-api_internal_dtos_request.ForgotPasswordDto:
    properties:
      email:
        maxLength: 255
        minLength: 5
        type: string
      new_password:
        maxLength: 64
        minLength: 8
        type: string
      token_id:
        type: string
    required:
    - email
    - new_password
    - token_id
    type: object
  history-api_internal_dtos_request.SignInDto:
    properties:
      email:
        maxLength: 255
        minLength: 5
        type: string
      password:
        maxLength: 64
        minLength: 8
        type: string
    required:
    - email
    - password
    type: object
  history-api_internal_dtos_request.SignUpDto:
    properties:
      display_name:
        maxLength: 50
        minLength: 2
        type: string
      email:
        maxLength: 255
        minLength: 5
        type: string
      password:
        maxLength: 64
        minLength: 8
        type: string
      token_id:
        type: string
    required:
    - display_name
    - email
    - password
    - token_id
    type: object
  history-api_internal_dtos_request.UpdateProfileDto:
    properties:
      avatar_url:
        type: string
      bio:
        maxLength: 255
        type: string
      country_code:
        type: string
      display_name:
        maxLength: 50
        minLength: 2
        type: string
      full_name:
        maxLength: 100
        minLength: 2
        type: string
      location:
        maxLength: 100
        type: string
      phone:
        maxLength: 20
        minLength: 8
        type: string
      website:
        type: string
    type: object
  history-api_internal_dtos_request.VerifyTokenDto:
    properties:
      email:
        type: string
      token:
        type: string
      token_type:
        allOf:
        - $ref: '#/definitions/history-api_pkg_constants.TokenType'
        enum:
        - 1
        - 2
        - 3
        - 4
    required:
    - email
    - token
    - token_type
    type: object
  history-api_internal_dtos_response.CommonResponse:
    properties:
      data: {}
      message:
        type: string
      status:
        type: boolean
    type: object
  history-api_internal_dtos_response.PaginatedResponse:
    properties:
      data: {}
      message:
        type: string
      pagination:
        properties:
          has_more:
            type: boolean
          next_cursor:
            type: string
        type: object
      status:
        type: boolean
    type: object
  history-api_pkg_constants.TokenType:
    enum:
    - 1
    - 2
    - 3
    - 4
    format: int32
    type: integer
    x-enum-varnames:
    - TokenPasswordReset
    - TokenEmailVerify
    - TokenMagicLink
    - TokenUpload
info:
  contact:
    email: support@swagger.io
    name: API Support
    url: http://www.swagger.io/support
  description: This is a sample server for History API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: History API
  version: "1.0"
paths:
  /auth/forgot-password:
    post:
      consumes:
      - application/json
      description: Initiate password recovery process for a user
      parameters:
      - description: Forgot Password request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.ForgotPasswordDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Handle forgotten password
      tags:
      - Auth
  /auth/google/callback:
    get:
      description: Receives the auth code from Google, exchanges it for tokens, creates/logs
        in the user, and redirects back to the frontend with application tokens.
      parameters:
      - description: Security state string
        in: query
        name: state
        required: true
        type: string
      - description: Authorization code from Google
        in: query
        name: code
        required: true
        type: string
      responses:
        "302":
          description: Redirect to Frontend with JWTs
          schema:
            type: string
        "401":
          description: Invalid state
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Handle Google OAuth2 callback
      tags:
      - Auth
  /auth/google/login:
    get:
      description: Generates a state string, sets it in a cookie, and redirects the
        user to Google's consent page.
      responses:
        "302":
          description: Redirect to Google
          schema:
            type: string
      summary: Initiate Google OAuth2 login
      tags:
      - Auth
  /auth/refresh:
    post:
      consumes:
      - application/json
      description: Generate a new access token using a valid refresh token from context
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "401":
          description: Unauthorized or expired refresh token
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Refresh session tokens
      tags:
      - Auth
  /auth/signin:
    post:
      consumes:
      - application/json
      description: Authenticate user credentials and return access/refresh tokens
      parameters:
      - description: Sign In credentials
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.SignInDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "401":
          description: Invalid credentials
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Sign in a user
      tags:
      - Auth
  /auth/signup:
    post:
      consumes:
      - application/json
      description: Create a new user account in the system
      parameters:
      - description: Sign Up details
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.SignUpDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Register a new user
      tags:
      - Auth
  /auth/token/create:
    post:
      consumes:
      - application/json
      description: Request a new token for specific actions like email confirmation
      parameters:
      - description: Token creation request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.CreateTokenDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Generate a new verification token
      tags:
      - Auth
  /auth/token/verify:
    post:
      consumes:
      - application/json
      description: Validate an OTP or email verification token
      parameters:
      - description: Token verification data
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.VerifyTokenDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Verify a security token
      tags:
      - Auth
  /media:
    get:
      consumes:
      - application/json
      description: Search media with filters, pagination
      parameters:
      - description: Page number
        in: query
        name: page
        type: integer
      - description: Items per page
        in: query
        name: limit
        type: integer
      - description: Search keyword
        in: query
        name: keyword
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.PaginatedResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Search media
      tags:
      - Media
  /media/{id}:
    delete:
      consumes:
      - application/json
      description: Delete a media file by ID
      parameters:
      - description: Media ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Delete media
      tags:
      - Media
    get:
      consumes:
      - application/json
      description: Retrieve a media file by its ID
      parameters:
      - description: Media ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Get media by ID
      tags:
      - Media
  /media/presigned:
    get:
      consumes:
      - application/json
      description: Generate a presigned URL for direct upload to storage
      parameters:
      - description: File name
        in: query
        name: filename
        required: true
        type: string
      - description: Content type
        in: query
        name: contentType
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Generate presigned URL
      tags:
      - Media
  /media/presigned/complete:
    post:
      consumes:
      - application/json
      description: Confirm that upload via presigned URL is completed
      parameters:
      - description: Storage key
        in: query
        name: key
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Confirm presigned upload
      tags:
      - Media
  /media/upload:
    post:
      consumes:
      - multipart/form-data
      description: Upload media file through server
      parameters:
      - description: Upload file
        in: formData
        name: file
        required: true
        type: file
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Upload media (server-side)
      tags:
      - Media
  /roles:
    get:
      consumes:
      - application/json
      description: Get a list of all roles in the system
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - ApiKeyAuth: []
      summary: Get all roles
      tags:
      - Roles
  /roles/{id}:
    get:
      consumes:
      - application/json
      description: Get detailed information about a specific role
      parameters:
      - description: Role ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - ApiKeyAuth: []
      summary: Get role by ID
      tags:
      - Roles
  /tiles/{z}/{x}/{y}:
    get:
      description: Fetch vector or raster map tile data by Z, X, Y coordinates
      parameters:
      - description: Zoom level (0-22)
        in: path
        name: z
        required: true
        type: integer
      - description: X coordinate
        in: path
        name: x
        required: true
        type: integer
      - description: Y coordinate
        in: path
        name: "y"
        required: true
        type: integer
      produces:
      - application/octet-stream
      responses:
        "200":
          description: OK
          schema:
            type: file
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Get a map tile
      tags:
      - Tile
  /tiles/metadata:
    get:
      consumes:
      - application/json
      description: Retrieve map metadata
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Get tile metadata
      tags:
      - Tile
  /users:
    get:
      consumes:
      - application/json
      description: Search and filter users with pagination (Admin/Mod only)
      parameters:
      - in: query
        name: cursor
        type: string
      - in: query
        name: is_deleted
        type: boolean
      - in: query
        maximum: 100
        minimum: 1
        name: limit
        required: true
        type: integer
      - enum:
        - asc
        - desc
        in: query
        name: order
        type: string
      - collectionFormat: csv
        in: query
        items:
          type: string
        name: role_ids
        type: array
      - in: query
        maxLength: 200
        minLength: 2
        name: search
        type: string
      - enum:
        - id
        - created_at
        - updated_at
        in: query
        name: sort
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.PaginatedResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Search users
      tags:
      - Users
  /users/{id}:
    delete:
      consumes:
      - application/json
      description: Soft delete a user account (Admin/Mod only)
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Delete a user
      tags:
      - Users
    get:
      consumes:
      - application/json
      description: Retrieve details of a specific user (Admin/Mod only)
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Get user by ID
      tags:
      - Users
    put:
      consumes:
      - application/json
      description: Update the profile details of the currently authenticated user
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: string
      - description: Update Profile request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.UpdateProfileDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Update user profile
      tags:
      - Users
  /users/{id}/media:
    get:
      consumes:
      - application/json
      description: Retrieve media list by specific user ID
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      summary: Get user's media by user ID
      tags:
      - Users
  /users/{id}/password:
    patch:
      consumes:
      - application/json
      description: Update the password for the currently authenticated user
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: string
      - description: Change Password request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.ChangePasswordDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Change user password
      tags:
      - Users
  /users/{id}/restore:
    patch:
      consumes:
      - application/json
      description: Restore a soft-deleted user account (Admin/Mod only)
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Restore a deleted user
      tags:
      - Users
  /users/{id}/role:
    patch:
      consumes:
      - application/json
      description: Update the role of a user (Admin only)
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: string
      - description: Change Role request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/history-api_internal_dtos_request.ChangeRoleDto'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Change user role
      tags:
      - Users
  /users/current:
    get:
      consumes:
      - application/json
      description: Retrieve the profile information of the currently authenticated
        user
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Get current user profile
      tags:
      - Users
  /users/current/media:
    get:
      consumes:
      - application/json
      description: Retrieve media list of the currently authenticated user
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/history-api_internal_dtos_response.CommonResponse'
      security:
      - BearerAuth: []
      summary: Get current user's media
      tags:
      - Users
securityDefinitions:
  BearerAuth:
    description: Type "Bearer " followed by a space and JWT token.
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"