openapi: 3.0.3
info:
  version: v1.0.3
  title: LE-KO Events API
  license:
    name: private
    url: https://le-ko.deggex.com
  contact:
    email: denis@deggex.awsapps.com
  description: LE-KO Events API
servers:
  - url: https://booking-{env}.le-ko.deggex.com/{basePath}
    description: Addreses APIs.
    variables:
      basePath:
        default: v1
      env:
        default: dev
security:
  - bearerHttpAuthentication: []
tags:
  - name: Bookings
    description: Bookings APIs
  - name: Addresses
    description: Addresses APIs
  - name: Events
    description: Events APIs
  - name: Moderation
    description: Content Moderation APIs
  - name: Admin Panel
    description: Admin Panel APIs for content moderation and management
  - name: Ratings
    description: Ratings APIs
  - name: Services
    description: Services APIs
  - name: Sessions
    description: Session APIs
paths:
  /addresses:
    get:
      summary: Get filtered addresses
      operationId: getFilteredAddresses
      description: |
        ✨ Gets addresses by filters. You must specify either `userId` or a combination of  `lat`, `lng`, and `distanceMeters` to filter the addresses.
      tags:
        - Addresses
      parameters:
        - name: userId
          in: query
          required: false
          description: The user ID to filter addresses
          schema:
            $ref: '#/components/schemas/Id'
        - name: lat
          in: query
          required: false
          description: Latitude for location-based filtering
          schema:
            type: number
            format: double
        - name: lng
          in: query
          required: false
          description: Longitude for location-based filtering
          schema:
            type: number
            format: double
        - name: distanceMeters
          in: query
          required: false
          description: Distance in meters for location-based filtering
          schema:
            type: integer
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of filtered addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      summary: Register a new address
      operationId: createAddress
      description: |
        ✨ Register a new address. The formatted address should ideally match exactly the format returned by the geosuggest API. This ensures consistency and accuracy when storing and retrieving address information.
      tags:
        - Addresses
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
      responses:
        '200':
          description: Address registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /addresses/suggest:
    get:
      summary: Suggest addresses
      operationId: suggestAddresses
      description: ✨ Suggest addresses based on a query string.
      tags:
        - Addresses
      parameters:
        - name: query
          in: query
          required: true
          description: The query string to suggest addresses
          schema:
            type: string
        - name: baseLat
          in: query
          required: false
          description: Optional base latitude for location-based suggestions
          schema:
            type: number
            format: float
            minimum: -90
            maximum: 90
        - name: baseLong
          in: query
          required: false
          description: Optional base longitude for location-based suggestions
          schema:
            type: number
            format: float
            minimum: -180
            maximum: 180
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of suggested addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeosuggestedAddress'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /addresses/geocode:
    get:
      summary: Geocode addresses
      operationId: geocodeAddresses
      description: |
        ✨ Geocoding is the process of converting addresses into geographic coordinates. This endpoint suggests addresses based on a query string and returns their corresponding geographic coordinates.
      tags:
        - Addresses
      parameters:
        - name: query
          in: query
          required: true
          description: The query string to suggest addresses
          schema:
            type: string
            minLength: 1
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of geocoded addresses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GeocodedAddress'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /addresses/reversegeocode:
    get:
      summary: Reverse geocode.
      operationId: reverseGeocode
      description: |
        ✨ Reverse geocoding is the process of converting geographic coordinates into human-readable addresses. This endpoint returns suggested addresses based on the provided geographic coordinates in the query string.
      tags:
        - Addresses
      parameters:
        - name: latitude
          in: query
          required: true
          description: Latitude to reverse geocode.
          schema:
            type: number
            format: double
            minimum: -90
            maximum: 90
        - name: longitude
          in: query
          required: true
          description: longitude to reverse geocode.
          schema:
            type: number
            format: double
            minimum: -180
            maximum: 180
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of geocoded addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodedAddress'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /addresses/{addressId}:
    get:
      summary: Get an address by ID
      operationId: getAddressById
      description: ✨ Retrieve a specific address using its unique ID.
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            $ref: '#/components/schemas/Id'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Address details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Address not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update an address
      operationId: updateAddress
      description: ✨ Update an address by replacing all fields.
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            $ref: '#/components/schemas/Id'
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
      responses:
        '200':
          description: Address updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete an address
      operationId: deleteAddress
      description: ✨ Delete an address by ID.
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            $ref: '#/components/schemas/Id'
        - name: currentUserId
          in: query
          required: true
          description: The user of the ID attempting this operation
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Address deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Current user is forbidden from this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /addresses/{addressId}/type:
    post:
      operationId: setUserAddressType
      summary: Set the type of an address
      description: ✨ Sets the type of an address and unsets any other addresses of said type for the  same user
      tags:
        - Addresses
      parameters:
        - name: addressId
          in: path
          required: true
          description: The address ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetUserAddressType'
      responses:
        '200':
          description: Status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Address doesn't exist or user has no permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /addresses/nearby:
    get:
      summary: Get nearby users based on addresses
      operationId: getNearbyUsers
      description: |
        ✨ Retrieves user IDs of nearby users based on a provided
        latitude and longitude. This endpoint returns a list of
        user IDs for users located within a certain radius of the
        given coordinates.
      tags:
        - Addresses
      parameters:
        - name: userId
          in: query
          required: true
          description: The ID of the user which is requesting other nearby users. This is used to filter them out of the results.
          schema:
            type: string
            format: uuid
        - name: latitude
          in: query
          required: true
          schema:
            type: number
            format: double
        - name: longitude
          in: query
          required: true
          schema:
            type: number
            format: double
        - name: maxDistanceInMeters
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of nearby user IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /bookings/{bookingId}/cancel:
    post:
      operationId: cancelBooking
      summary: Cancel a booking
      description: ✨ Cancel a specific booking with automatic role determination based on user ID
      tags:
        - Bookings
      parameters:
        - name: bookingId
          in: path
          required: true
          description: The booking ID to cancel
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelBookingRequest'
      responses:
        '204':
          description: Booking canceled successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Forbidden - User not authorized to cancel this booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Booking not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /bookings/{bookingId}/dispute:
    post:
      operationId: postBookingDispute
      summary: Dispute a booking.
      description: ✨ Dispute a booking.
      tags:
        - Bookings
      parameters:
        - name: bookingId
          in: path
          required: true
          description: The booking ID.
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisputeInput'
      responses:
        '200':
          description: Dispute successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullBooking'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: getBookingDispute
      summary: Get booking dispute user ID and dispute reason.
      description: ✨ Get booking dispute user ID and dispute reason.
      tags:
        - Bookings
      parameters:
        - name: bookingId
          in: path
          required: true
          description: The booking ID.
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Dispute data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeWithBooking'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /bookings/disputereasons:
    get:
      operationId: getAllDisputeReasons
      summary: Lists all valid dispute reasons
      description: ✨ Lists all valid dispute reasons.
      tags:
        - Bookings
      parameters:
        - name: type
          in: query
          required: false
          description: Filter dispute reasons by type
          schema:
            $ref: '#/components/schemas/BookingDisputeReasonType'
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of dispute reasons.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BookingDisputeReason'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /booking-orders/{orderId}:
    get:
      summary: Get all bookings for a specific order with complete details
      operationId: getBookingsByOrderId
      description: ✨ Retrieves all bookings associated with a specific booking order ID, including complete details of events, timeslots, sessions, services, and addresses.
      tags:
        - Bookings
      parameters:
        - name: orderId
          in: path
          required: true
          description: The booking order ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of bookings with complete details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BookingWithDetails'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Booking order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /events/coaches/aggregates/{coachId}:
    get:
      summary: Get grouped booking and event data
      description: ✨ Get grouped booking and event data
      operationId: getGroupedBookingAndEventByCoachId
      tags:
        - Events
      parameters:
        - name: coachId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: startTime
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start time for filtering events (ISO 8601 format)
        - name: endTime
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: End time for filtering events (ISO 8601 format)
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventWithBookingsTimeslotService'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/{eventId}/aggregate:
    get:
      summary: Get aggregate data for an event
      description: ✨ Gets aggregated data for an event
      operationId: getAggregateEventData
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: bookingId
          in: query
          required: false
          description: Optional booking ID(s) to filter correlated bookings. If provided, only bookings matching these IDs will be returned, regardless of their status (including canceled bookings).
          schema:
            type: array
            items:
              type: string
              format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Aggregate event data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateEventData'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/{eventId}/restore:
    post:
      operationId: restoreDeletedEvent
      summary: Restore a deleted event
      description: ✨ Restore a deleted event
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          description: Event ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Event restored
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/{eventId}/cancel:
    post:
      operationId: cancelEventById
      summary: Cancels an event
      description: ✨ Cancels an event
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          description: Event ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelEventRequest'
      responses:
        '204':
          description: Event canceled
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - User is not authorized to cancel this event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/{eventId}/dismiss:
    post:
      summary: Dismiss a canceled event
      operationId: dismissEvent
      description: |
        ✨ Dismiss a canceled event from the coach's calendar view. Only the event owner
        (coach) can dismiss their own events, and only canceled events can be dismissed.
        This action is permanent and helps keep the calendar UI clean.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          description: The event ID to dismiss
          schema:
            type: string
            format: uuid
        - name: coachId
          in: query
          required: true
          description: The coach ID (must match the event owner)
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Event dismissed successfully
        '400':
          description: Bad Request - event is not canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - coach does not own this event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/{eventId}/rate:
    post:
      operationId: rateEventById
      summary: Rate an event by its ID
      description: ✨ Rate an event by its ID, as well as the booking ID
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          description: Event ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RateEventCreate'
      responses:
        '204':
          description: Event rated successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Invalid user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/{eventId}:
    get:
      operationId: getEventWithBookings
      description: ✨ Get event with complete details and bookings
      summary: Get event with complete details and bookings
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          description: Event ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Event details with bookings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventWithBookingsAndDetails'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteEventById
      summary: Delete an event
      description: |
        ✨ Delete or cancel an event by its ID.
        - If `agentId` is provided: Cancel the event (support agent action)
        - If `userId` is provided: Delete the event if eligible (owner action). Event can only be deleted if it has no bookings or only canceled bookings
        - Either `agentId` or `userId` must be provided, but not both
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          description: Event ID
          schema:
            type: string
            format: uuid
        - name: agentId
          in: query
          required: false
          description: Support agent ID
          schema:
            type: string
            format: uuid
        - name: userId
          in: query
          required: false
          description: Event owner ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Event deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/scheduled:
    get:
      operationId: getUpcomingScheduledEvents
      summary: Get events within the next 24 hours.
      description: |
        ✨ Gets events, alongside with their respective bookings, that are scheduled to happen in the next 24 hours.
      tags:
        - Events
      parameters:
        - name: startTime
          in: query
          required: true
          description: Start of the time window (ISO 8601 format).
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          required: true
          description: End of the time window (ISO 8601 format).
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          required: true
          description: Maximum number of events to return.
          schema:
            type: integer
            minimum: 1
        - name: offset
          in: query
          required: true
          description: Number of events to skip before starting to collect the result set.
          schema:
            type: integer
            minimum: 0
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: All events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventWithBookings'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /events/gcalendars/credentials:
    post:
      operationId: postGoogleCalendarCredentials
      summary: Post Google Calendar credentials
      description: |
        ✨ Post Google Calendar credentials. These will be used for syncing events to a user's
        calendar
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventsGoogleCalendarCredentials'
      responses:
        '204':
          description: Credentials created successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteGoogleCalendarCredentials
      summary: Delete Google Calendar credentials
      description: |
        ✨ Delete Google Calendar credentials for a user. This will remove the stored
        credentials and stop syncing events to the user's calendar.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
        - name: userId
          in: query
          required: true
          description: UUID of the user whose credentials should be deleted
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Credentials deleted successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Credentials not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/deletion-eligibility:
    get:
      summary: Check user deletion eligibility
      description: ✨ Check if a user can be safely deleted by verifying they have no future events (as coach) or bookings (as athlete)
      operationId: checkUserDeletionEligibility
      tags:
        - Events
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The user ID to check for deletion eligibility
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDeletionEligibility'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /timeslots/{timeslotId}:
    delete:
      operationId: deleteFutureEventsByTimeslot
      summary: Delete all future events for a timeslot
      description: |
        ✨ Deletes all future events associated with a specific timeslot.
        - Requires userId query parameter for authentication
        - Only deletes events where LOWER(time_range) > current time
        - All-or-nothing operation: fails if ANY future event has active bookings
        - User must be the owner (coach) of the timeslot
      tags:
        - Events
      parameters:
        - name: timeslotId
          in: path
          required: true
          description: Timeslot ID
          schema:
            type: string
            format: uuid
        - name: userId
          in: query
          required: true
          description: Coach/owner user ID
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Future events deleted successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Timeslot not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /moderations/posts:
    post:
      operationId: moderatePost
      summary: Moderate a post
      description: ✨ Mark a post as moderated with a specified reason
      tags:
        - Moderation
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModerationRequest'
      responses:
        '201':
          description: Post has been successfully moderated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModeratedPost'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /moderations/posts/{postId}:
    get:
      operationId: getModeratedPost
      summary: Get moderated post details
      description: ✨ Get details of a moderated post by post ID
      tags:
        - Moderation
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PostId'
          description: ID of the post to get moderation details for
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Moderated post details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModeratedPost'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /moderations/posts/{postId}/status:
    get:
      operationId: checkPostModerationStatus
      summary: Check if post is moderated
      description: ✨ Check whether a specific post is currently moderated
      tags:
        - Moderation
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PostId'
          description: ID of the post to check moderation status for
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Post moderation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /moderations/comments:
    post:
      operationId: moderateComment
      summary: Moderate a comment
      description: ✨ Mark a comment as moderated with a specified reason
      tags:
        - Moderation
      parameters:
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentModerationRequest'
      responses:
        '201':
          description: Comment has been successfully moderated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModeratedComment'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /moderations/comments/{commentId}:
    get:
      operationId: getModeratedComment
      summary: Get moderated comment details
      description: ✨ Get details of a moderated comment by comment ID
      tags:
        - Moderation
      parameters:
        - name: commentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/CommentId'
          description: ID of the comment to get moderation details for
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Moderated comment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModeratedComment'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /moderations/comments/{commentId}/status:
    get:
      operationId: checkCommentModerationStatus
      summary: Check if comment is moderated
      description: ✨ Check whether a specific comment is currently moderated
      tags:
        - Moderation
      parameters:
        - name: commentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/CommentId'
          description: ID of the comment to check moderation status for
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Comment moderation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentModerationStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /administrations/flagged-content:
    get:
      operationId: getFlaggedContent
      summary: Get flagged content feed
      description: ✨ Get paginated list of AI-flagged content (posts and comments) for admin review
      tags:
        - Admin Panel
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Page number (0-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of items per page
        - name: userId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter by user ID
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter by content created on or after this date
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter by content created on or before this date
        - name: pendingReview
          in: query
          required: false
          schema:
            type: boolean
          description: Filter by review status (true = pending automatic moderation, false = already reviewed automatically or manually)
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of flagged content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FlaggedContent'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /administrations/posts/{postId}/safety-override:
    put:
      operationId: setPostSafetyOverride
      summary: Set manual safety override for post
      description: ✨ Admin manually reviews and approves/rejects AI-flagged post
      tags:
        - Admin Panel
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the post to review
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: boolean
              description: Whether the content should be approved (true) or kept hidden (false)
      responses:
        '204':
          description: Safety override successfully set
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Post not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /administrations/comments/{commentId}/safety-override:
    put:
      operationId: setCommentSafetyOverride
      summary: Set manual safety override for comment
      description: ✨ Admin manually reviews and approves/rejects AI-flagged comment
      tags:
        - Admin Panel
      parameters:
        - name: commentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the comment to review
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: boolean
              description: Whether the content should be approved (true) or kept hidden (false)
      responses:
        '204':
          description: Safety override successfully set
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Comment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /administrations/content-reports:
    get:
      operationId: getAllContentReports
      summary: Get all content reports
      description: ✨ Get paginated list of user-submitted content reports for admin review
      tags:
        - Admin Panel
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Page number (0-indexed)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of items per page
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: List of content reports
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContentReport'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /administrations/content-reports/{reportId}:
    get:
      operationId: getContentReport
      summary: Get content report by ID
      description: ✨ Retrieve a specific content report by its ID
      tags:
        - Admin Panel
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Content report ID
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Content report details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentReport'
        '404':
          description: Content report not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteContentReport
      summary: Delete content report
      description: ✨ Delete a content report by its ID
      tags:
        - Admin Panel
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Content report ID
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '204':
          description: Content report deleted successfully
        '404':
          description: Content report not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ratings/services/{serviceId}:
    get:
      operationId: getServiceRating
      description: ✨ Get the rating of a given service
      summary: Get the rating of a given service
      tags:
        - Ratings
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: The rating information for the service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rating'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ratings/coaches/{coachId}:
    get:
      operationId: getCoachRating
      description: ✨ Get the rating of a given coach
      summary: Get the rating of a given coach
      tags:
        - Ratings
      parameters:
        - name: coachId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: The rating information for the coach
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rating'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ratings/events/{eventId}:
    get:
      operationId: getEventRating
      description: ✨ Get the rating that a specific user gave to an event
      summary: Get user's rating for an event
      tags:
        - Ratings
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: userId
          in: query
          required: true
          description: User ID who made the rating
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The user's rating for the event
          content:
            application/json:
              schema:
                type: integer
                minimum: 0
                maximum: 5
                description: The rating value given by the user for this event
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Rating not found for this user and event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /coaches/{coachId}/services:
    get:
      operationId: getAllServices
      summary: Get all services
      description: ✨ Get all services
      tags:
        - Services
      parameters:
        - name: coachId
          in: path
          required: true
          description: ID of the Coach
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Service list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ServiceWithRating'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: createService
      summary: Create a new service
      description: ✨ Create a new service
      tags:
        - Services
      parameters:
        - name: coachId
          in: path
          required: true
          description: ID of the Coach
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceRequest'
      responses:
        '200':
          description: Coach service has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceWithRating'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /coaches/{coachId}/services/{serviceId}:
    get:
      operationId: getServiceById
      summary: Get service by id
      description: ✨ Get service by id
      tags:
        - Services
      parameters:
        - name: coachId
          in: path
          required: true
          description: ID of the Coach
          schema:
            type: string
            format: uuid
        - name: serviceId
          in: path
          required: true
          description: ID of the Coach Service
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Service details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceWithRating'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    put:
      operationId: updateService
      summary: Update service
      description: ✨ Update service
      tags:
        - Services
      parameters:
        - name: coachId
          in: path
          required: true
          description: ID of the Coach
          schema:
            type: string
            format: uuid
        - name: serviceId
          in: path
          required: true
          description: ID of the Coach Service
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceRequest'
      responses:
        '200':
          description: Service has been updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceWithRating'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: deleteService
      summary: Delete service
      description: ✨ Delete service
      tags:
        - Services
      parameters:
        - name: coachId
          in: path
          required: true
          description: ID of the Coach
          schema:
            type: string
            format: uuid
        - name: serviceId
          in: path
          required: true
          description: ID of the Coach Service
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      responses:
        '200':
          description: Service has been deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  serviceId:
                    type: string
                    format: uuid
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /sessions:
    post:
      summary: Create a new session with timeslots
      operationId: createSessionWithTimeslots
      description: ✨ Create a new session with associated timeslots for a specific service.
      tags:
        - Sessions
      parameters:
        - name: currentUserId
          in: query
          required: true
          description: UUID of the user creating the session
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/TraceparentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreate'
      responses:
        '201':
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionCreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found or forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer token using a JWT
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Id:
      type: string
      example: 4b72d209-debd-45e1-93cc-7640bf7d39bf
      description: Database entity primary key uuid
      format: uuid
      maxLength: 36
      minLength: 36
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    AddressType:
      type: string
      enum:
        - Main
    Address:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        formattedAddress:
          type: string
        addressType:
          $ref: '#/components/schemas/AddressType'
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        entrance:
          type: string
        floor:
          type: string
        locationComment:
          type: string
      required:
        - id
        - userId
        - formattedAddress
    Error:
      type: object
      required:
        - code
        - message
        - endpoint
        - requestId
      properties:
        code:
          type: string
          description: Error unique code
          enum:
            - validation
            - internal
            - oops
            - unexpected
            - tooManyRequests
            - notFound
            - unauthorized
            - forbidden
        message:
          type: string
          description: Error message
        endpoint:
          type: string
        requestId:
          type: string
    Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    AddressCreate:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        formattedAddress:
          type: string
        entrance:
          type: string
        floor:
          type: string
        locationComment:
          type: string
        type:
          $ref: '#/components/schemas/AddressType'
      required:
        - userId
        - formattedAddress
    GeosuggestedAddress:
      type: object
      required:
        - formattedAddress
        - street
        - region
        - city
      properties:
        formattedAddress:
          type: string
        street:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
    GeocodedAddress:
      type: object
      required:
        - formattedAddress
        - latitude
        - longitude
        - street
        - region
        - city
      properties:
        formattedAddress:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        street:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
    SetUserAddressType:
      type: object
      properties:
        currentUserId:
          type: string
          format: uuid
        addressType:
          $ref: '#/components/schemas/AddressType'
      required:
        - currentUserId
        - addressType
    BookingCancellationReasonCode:
      type: string
      description: Reason code for booking cancellation
      enum:
        - NotFeelingWell
        - NoTime
        - Other
    CancelBookingRequest:
      type: object
      required:
        - cancellationReasonCode
      properties:
        userId:
          type: string
          format: uuid
          nullable: true
          description: User initiating cancellation (athlete/coach). If not provided or null, cancellation is performed by the system.
        cancellationReasonCode:
          $ref: '#/components/schemas/BookingCancellationReasonCode'
        cancellationReasonText:
          type: string
          description: Optional additional details about the cancellation
    BookingDisputeReasonType:
      type: string
      enum:
        - Athlete
        - Coach
    BookingDisputeReason:
      type: object
      properties:
        id:
          type: string
          format: uuid
        category:
          type: string
        title:
          type: string
        description:
          type: string
        type:
          $ref: '#/components/schemas/BookingDisputeReasonType'
      required:
        - id
        - category
        - title
        - description
        - type
    BookingStatus:
      type: string
      enum:
        - Accepted
        - Rejected
        - Pending
        - Canceled
        - InDispute
        - DisputeDone
    BookingCanceledByRole:
      type: string
      description: Who canceled the booking
      enum:
        - Athlete
        - Coach
        - System
    Booking:
      type: object
      properties:
        bookingId:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        eventId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/BookingStatus'
        completed:
          type: boolean
        note:
          type: string
          nullable: true
        canceledAt:
          type: string
          format: date-time
          nullable: true
        canceledByRole:
          allOf:
            - $ref: '#/components/schemas/BookingCanceledByRole'
          type: string
          nullable: true
        cancellationReasonCode:
          allOf:
            - $ref: '#/components/schemas/BookingCancellationReasonCode'
          type: string
          nullable: true
        cancellationReasonText:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
      required:
        - bookingId
        - orderId
        - userId
        - eventId
        - status
        - completed
        - createdAt
    DisputeWithBooking:
      type: object
      properties:
        disputerUserId:
          type: string
          format: uuid
        comment:
          type: string
        reason:
          $ref: '#/components/schemas/BookingDisputeReason'
        booking:
          $ref: '#/components/schemas/Booking'
      required:
        - disputerUserId
        - reason
        - booking
    DisputeInput:
      type: object
      properties:
        disputerUserId:
          type: string
          format: uuid
        reasonId:
          type: string
          format: uuid
        comment:
          type: string
      required:
        - reasonId
        - disputerUserId
    EventStatus:
      type: string
      enum:
        - Scheduled
        - Canceled
        - InProgress
        - Done
    EventCanceledByRole:
      type: string
      enum:
        - Coach
        - System
      description: Role of who canceled the event
    EventCancellationReasonCode:
      type: string
      enum:
        - NotFeelingWell
        - NoTime
        - Other
      description: Reason code for event cancellation
    Event:
      type: object
      properties:
        id:
          type: string
          format: uuid
        timeslotId:
          type: string
          format: uuid
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/EventStatus'
          nullable: true
        coachId:
          type: string
          format: uuid
        canceledAt:
          type: string
          format: date-time
          nullable: true
        canceledByRole:
          allOf:
            - $ref: '#/components/schemas/EventCanceledByRole'
          type: string
          nullable: true
        cancellationReasonCode:
          allOf:
            - $ref: '#/components/schemas/EventCancellationReasonCode'
          type: string
          nullable: true
        cancellationReasonText:
          type: string
          nullable: true
      required:
        - id
        - timeslotId
        - startTime
        - endTime
        - status
        - coachId
    Currency:
      type: string
      enum:
        - RUB
    Timeslot:
      type: object
      properties:
        id:
          type: string
          format: uuid
        sessionId:
          type: string
          format: uuid
        startTime:
          type: string
        endTime:
          type: string
        numberOfParticipants:
          type: integer
        slotType:
          type: string
          nullable: true
        ageStart:
          type: integer
        ageEnd:
          type: integer
        duration:
          type: integer
        price:
          type: integer
        priceCurrency:
          $ref: '#/components/schemas/Currency'
        public:
          type: boolean
          nullable: true
        level:
          type: string
          nullable: true
        eligibility:
          type: string
          nullable: true
        addressId:
          type: string
          format: uuid
          nullable: true
      required:
        - id
        - sessionId
        - startTime
        - endTime
        - numberOfParticipants
        - slotType
        - ageStart
        - ageEnd
        - duration
        - price
        - priceCurrency
        - public
        - level
        - eligibility
        - addressId
    Session:
      type: object
      properties:
        id:
          type: string
          format: uuid
        serviceId:
          type: string
          format: uuid
        startDate:
          type: string
          format: date-time
        repeatDays:
          type: array
          items:
            type: string
        stopDate:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - serviceId
        - startDate
        - repeatDays
        - stopDate
    Service:
      type: object
      properties:
        id:
          type: string
          format: uuid
        coachId:
          type: string
          format: uuid
        description:
          type: string
        sportId:
          type: string
          format: uuid
        subsportId:
          type: string
          format: uuid
          nullable: true
        isDraft:
          type: boolean
        inventory:
          type: string
          nullable: true
          description: Inventory details for the service
      required:
        - id
        - coachId
        - description
        - sportId
        - subsportId
        - isDraft
    FullBooking:
      type: object
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
        event:
          $ref: '#/components/schemas/Event'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        session:
          $ref: '#/components/schemas/Session'
        service:
          $ref: '#/components/schemas/Service'
      required:
        - booking
        - event
        - timeslot
        - session
        - service
    BookingWithDetails:
      type: object
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
        event:
          $ref: '#/components/schemas/Event'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        session:
          $ref: '#/components/schemas/Session'
        service:
          $ref: '#/components/schemas/Service'
      required:
        - booking
        - event
        - timeslot
        - session
        - service
    EventWithBookingsTimeslotService:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        service:
          $ref: '#/components/schemas/Service'
      required:
        - event
        - bookings
        - timeslot
        - service
    BookingDispute:
      type: object
      properties:
        disputerUserId:
          type: string
          format: uuid
        comment:
          type: string
        reason:
          $ref: '#/components/schemas/BookingDisputeReason'
      required:
        - disputerUserId
        - comment
        - reason
    AggregateEventDataBE:
      type: object
      description: A booking with its event
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
        event:
          $ref: '#/components/schemas/Event'
        bookingDispute:
          $ref: '#/components/schemas/BookingDispute'
      required:
        - booking
        - event
    AggregateEventDataCR:
      type: object
      description: Correlated bookings to an event.
      properties:
        userId:
          type: string
          format: uuid
        bookingsAndEvents:
          type: array
          items:
            $ref: '#/components/schemas/AggregateEventDataBE'
      required:
        - userId
        - bookingsAndEvents
    AggregateEventData:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        session:
          $ref: '#/components/schemas/Session'
        service:
          $ref: '#/components/schemas/Service'
        address:
          $ref: '#/components/schemas/Address'
        futureEventsCount:
          type: integer
          description: |
            How many future events are there with the same timeslot ID. Useful for detecting
            whether it's a repeating event or timeslot.
        correlatedBookings:
          type: array
          items:
            $ref: '#/components/schemas/AggregateEventDataCR'
      required:
        - event
        - timeslot
        - session
        - service
        - address
        - futureEventsCount
        - correlatedBookings
    CancelEventRequest:
      type: object
      required:
        - cancellationReasonCode
      properties:
        userId:
          type: string
          format: uuid
          description: ID of the user canceling the event. If absent, indicates system-initiated cancellation.
        cancellationReasonCode:
          $ref: '#/components/schemas/EventCancellationReasonCode'
        cancellationReasonText:
          type: string
          description: Optional free-form text explanation for the cancellation
    RateEventCreate:
      type: object
      properties:
        bookingId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        rating:
          type: integer
          minimum: 0
          maximum: 5
      required:
        - bookingId
        - userId
        - rating
    EventWithBookingsAndDetails:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        session:
          $ref: '#/components/schemas/Session'
        service:
          $ref: '#/components/schemas/Service'
        address:
          $ref: '#/components/schemas/Address'
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
      required:
        - event
        - timeslot
        - session
        - service
        - address
        - bookings
    EventWithBookings:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
      required:
        - event
        - bookings
    EventsGoogleCalendarCredentials:
      type: object
      properties:
        userId:
          type: string
          format: uuid
        accessToken:
          type: string
        refreshToken:
          type: string
      required:
        - userId
        - accessToken
        - refreshToken
    UserDeletionEligibility:
      type: object
      required:
        - hasFutureEvents
        - hasFutureBookings
        - canBeDeleted
      properties:
        hasFutureEvents:
          type: boolean
          description: Whether the user has future events as a coach (excluding cancelled events)
        hasFutureBookings:
          type: boolean
          description: Whether the user has future bookings as an athlete (excluding canceled/rejected bookings)
        canBeDeleted:
          type: boolean
          description: Whether the user can be safely deleted (true if both hasFutureEvents and hasFutureBookings are false)
    PostModerationReason:
      type: string
      enum:
        - nudity
        - racism
        - hate_speech
        - harassment
        - spam
        - violence
        - misinformation
        - copyright
        - inappropriate_content
        - other
      description: Reason for post moderation
    ModerationRequest:
      type: object
      required:
        - postId
        - reason
        - agentId
      properties:
        postId:
          type: string
          format: uuid
          description: ID of the post to moderate
        reason:
          $ref: '#/components/schemas/PostModerationReason'
          description: Reason for moderating the post
        agentId:
          type: string
          format: uuid
          description: ID of the user/agent moderating the post
        comment:
          type: string
          nullable: true
          description: Optional comment about the moderation action
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata about the moderation action
    ModeratedPost:
      type: object
      required:
        - id
        - postId
        - reason
        - agentId
        - metadata
      properties:
        id:
          $ref: '#/components/schemas/Id'
          description: Unique identifier for the moderated post entry
        postId:
          type: string
          format: uuid
        reason:
          $ref: '#/components/schemas/PostModerationReason'
          description: Reason why the post was moderated
        agentId:
          type: string
          format: uuid
          description: ID of the user/agent who moderated the post
        comment:
          type: string
          nullable: true
          description: Optional comment from the moderator
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata about the moderation action
    PostId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Post ID
      format: uuid
    ModerationStatus:
      type: object
      required:
        - moderated
      properties:
        moderated:
          type: boolean
          description: Whether the post is moderated or not
    CommentModerationRequest:
      type: object
      required:
        - commentId
        - reason
        - agentId
      properties:
        commentId:
          type: string
          format: uuid
          description: ID of the comment to moderate
        reason:
          $ref: '#/components/schemas/PostModerationReason'
          description: Reason for moderating the comment
        agentId:
          type: string
          format: uuid
          description: ID of the user/agent moderating the comment
        comment:
          type: string
          nullable: true
          description: Optional comment about the moderation action
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata about the moderation action
    ModeratedComment:
      type: object
      required:
        - id
        - commentId
        - reason
        - agentId
        - metadata
      properties:
        id:
          $ref: '#/components/schemas/Id'
          description: Unique identifier for the moderated comment entry
        commentId:
          type: string
          format: uuid
        reason:
          $ref: '#/components/schemas/PostModerationReason'
          description: Reason why the comment was moderated
        agentId:
          type: string
          format: uuid
          description: ID of the user/agent who moderated the comment
        comment:
          type: string
          nullable: true
          description: Optional comment from the moderator
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata about the moderation action
    CommentId:
      type: string
      example: 00000000-0000-1000-9000-510d9bb07630
      description: Comment ID
      format: uuid
    CommentModerationStatus:
      type: object
      required:
        - moderated
      properties:
        moderated:
          type: boolean
          description: Whether the comment is moderated or not
    FlaggedContent:
      type: object
      required:
        - contentType
        - contentId
        - userId
        - toxicityScore
        - manualSafetyOverride
        - createdAt
        - photoIds
      properties:
        contentType:
          type: string
          enum:
            - post
            - comment
          description: Type of content (post or comment)
        contentId:
          type: string
          format: uuid
          description: ID of the flagged content (post_id or comment_id)
        userId:
          type: string
          format: uuid
          description: ID of the user who created the content
        text:
          type: string
          nullable: true
          description: Text content of the post or comment
        toxicityScore:
          type: number
          format: double
          nullable: true
          description: AI confidence score for toxicity (0-1, higher = more toxic)
        manualSafetyOverride:
          type: boolean
          description: Whether an admin has manually reviewed this content
        createdAt:
          type: string
          format: date-time
          description: When the content was created
        postId:
          type: string
          format: uuid
          nullable: true
          description: For comments, the ID of the parent post
        photoIds:
          type: array
          items:
            type: string
            format: uuid
          description: Array of photo IDs if existent within a post
    ContentReport:
      type: object
      required:
        - contentReportId
        - reporterUserId
        - createdAt
      properties:
        contentReportId:
          type: string
          format: uuid
          description: Unique identifier for the content report
        reporterUserId:
          type: string
          format: uuid
          description: ID of the user who submitted the report
        postId:
          type: string
          format: uuid
          nullable: true
          description: ID of the reported post (null if reporting a comment)
        commentId:
          type: string
          format: uuid
          nullable: true
          description: ID of the reported comment (null if reporting a post)
        description:
          type: string
          nullable: true
          description: Optional text description explaining why this content was reported
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the report was created
    Rating:
      type: object
      properties:
        averageRating:
          type: number
          format: float
          minimum: 0
          maximum: 5
          description: The average rating value
        totalRatings:
          type: integer
          minimum: 0
          description: The total number of ratings received
      required:
        - averageRating
        - totalRatings
    Count:
      type: integer
      description: Page entries count
      example: 10
    CurrentPage:
      type: integer
      deprecated: true
      description: Current page
      example: 0
      minimum: 0
      default: 0
    PageNumber:
      type: integer
      description: Page number
      example: 0
      minimum: 0
      default: 0
    PageSize:
      type: integer
      deprecated: true
      description: Page size
      default: 10
      minimum: 1
      maximum: 100
      example: 10
    PageLimit:
      type: integer
      description: Page limit
      default: 10
      minimum: 1
      maximum: 100
      example: 10
    TotalCount:
      type: integer
      description: Total count
      default: 0
      minimum: 0
      example: 1000
    Page:
      type: object
      required:
        - count
        - page
        - limit
        - total
      properties:
        data:
          type: array
          items:
            type: object
        count:
          $ref: '#/components/schemas/Count'
        currentPage:
          $ref: '#/components/schemas/CurrentPage'
        page:
          $ref: '#/components/schemas/PageNumber'
        pageSize:
          $ref: '#/components/schemas/PageSize'
        limit:
          $ref: '#/components/schemas/PageLimit'
        total:
          $ref: '#/components/schemas/TotalCount'
    ServiceWithRating:
      type: object
      required:
        - coachId
        - serviceId
        - description
        - sportId
        - averageRating
        - totalRatings
        - hasFutureEvents
      properties:
        coachId:
          type: string
          format: uuid
        serviceId:
          type: string
          format: uuid
          example: 4b72d209-debd-45e1-93cc-7640bf7d39bf
          description: Service uuid
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        description:
          type: string
        sportId:
          type: string
          format: uuid
          example: 4b72d209-debd-45e1-93cc-7640bf7d39bf
          description: Sport Type UUID
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        subsportId:
          type: string
          format: uuid
          example: 4b72d209-debd-45e1-93cc-7640bf7d39bf
          description: Sport Type UUID
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          nullable: true
        isDraft:
          type: boolean
        inventory:
          type: string
          nullable: true
          description: Inventory details for the service
        averageRating:
          type: number
          format: float
          minimum: 0
          maximum: 5
          description: The average rating value
        totalRatings:
          type: integer
          minimum: 0
          description: The total number of ratings received
        hasFutureEvents:
          type: boolean
    CreateServiceRequest:
      type: object
      required:
        - sportId
        - description
      properties:
        description:
          type: string
          description: Description of the service
          maxLength: 2000
        sportId:
          type: string
          format: uuid
          description: ID of the sport for this service
        subsportId:
          type: string
          format: uuid
          nullable: true
          description: ID of the subsport (optional)
        isDraft:
          type: boolean
          description: Whether this service is a draft
          default: false
        inventory:
          type: string
          nullable: true
          description: Inventory details for the service
    UpdateServiceRequest:
      type: object
      required:
        - sportId
        - description
      properties:
        description:
          type: string
          description: Description of the service
          maxLength: 2000
        sportId:
          type: string
          format: uuid
          description: ID of the sport for this service
        subsportId:
          type: string
          format: uuid
          nullable: true
          description: ID of the subsport (optional)
        isDraft:
          type: boolean
          description: Whether this service is a draft
        inventory:
          type: string
          nullable: true
          description: Inventory details for the service
    Weekday:
      type: string
      enum:
        - Monday
        - Tuesday
        - Wednesday
        - Thursday
        - Friday
        - Saturday
        - Sunday
    TimeslotLevel:
      type: string
      enum:
        - Any
        - Beginner
        - Medium
        - Pro
    TimeslotEligibility:
      type: string
      enum:
        - All
        - Men
        - Women
    SessionTimeslotCreate:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
          description: |
            The start date and time for the  timeslot. While this field uses
            the date-time format, only the time component is utilized for scheduling
            purposes. The timezone information must be preserved and is required for
            accurate session scheduling across different geographical locations.
        durationMinutes:
          type: integer
          minimum: 30
        numberOfParticipants:
          type: integer
          minimum: 1
        addressId:
          type: string
          format: uuid
        ageStart:
          type: integer
          minimum: 1
        ageEnd:
          type: integer
          minimum: 1
        price:
          type: integer
          minimum: 1
        currency:
          $ref: '#/components/schemas/Currency'
        level:
          $ref: '#/components/schemas/TimeslotLevel'
        eligibility:
          $ref: '#/components/schemas/TimeslotEligibility'
      required:
        - startTime
        - durationMinutes
        - numberOfParticipants
        - addressId
        - ageStart
        - ageEnd
        - price
        - currency
        - level
        - eligibility
    SessionCreate:
      type: object
      properties:
        serviceId:
          type: string
          format: uuid
        startDate:
          type: string
          format: date-time
          description: |
            The start date and time for the session timeslot. While this field uses
            the date-time format, only the date component is utilized for scheduling
            purposes. The timezone information must be preserved and is required for
            accurate session scheduling across different geographical locations.
        stopDate:
          type: string
          format: date-time
          description: |
            The stop date and time for the session timeslot, only relevant for repeating
            sessions. While this field uses the date-time format, only the date
            component is utilized for scheduling purposes. The timezone information
            must be preserved and is required for accurate session scheduling across different
            geographical locations.
        repeatDays:
          type: array
          items:
            $ref: '#/components/schemas/Weekday'
        timeslots:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/SessionTimeslotCreate'
      required:
        - serviceId
        - startDate
        - stopDate
        - repeatDays
        - timeslots
    SessionCreateResponse:
      type: object
      properties:
        session:
          $ref: '#/components/schemas/Session'
        timeslots:
          type: array
          items:
            $ref: '#/components/schemas/Timeslot'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
      required:
        - session
        - timeslots
  parameters:
    TraceparentHeader:
      name: traceparent
      in: header
      required: false
      description: W3C Trace Context traceparent header for request tracing
      schema:
        type: string
        pattern: ^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$
        example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01