killrvideo_openapi.yaml

openapi: 3.1.0
info:
  title: KillrVideo v2 - Monolith Backend
  version: 2.0.0-alpha-local
paths:
  /api/v1/users/register:
    post:
      tags:
      - Users
      summary: Register new account
      operationId: register_user_api_v1_users_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/users/login:
    post:
      tags:
      - Users
      summary: "Login \u2192 JWT"
      operationId: login_for_access_token_api_v1_users_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserLoginResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/users/me:
    get:
      tags:
      - Users
      summary: Current user profile
      operationId: read_users_me_api_v1_users_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      security:
      - OAuth2PasswordBearer: []
    put:
      tags:
      - Users
      summary: Update profile
      operationId: update_users_me_api_v1_users_me_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserProfileUpdateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/v1/users/{user_id_path}:
    get:
      tags:
      - Users
      summary: Public user profile by ID
      description: Return basic user info (firstname, lastname, email, etc.) for a
        given UUID.
      operationId: get_user_by_id_api_v1_users__user_id_path__get
      parameters:
      - name: user_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos:
    post:
      tags:
      - Videos
      summary: Submit YouTube URL (async processing)
      description: 'Submit a new YouTube video for asynchronous processing.


        Only users with the *creator* or *moderator* role are authorized.'
      operationId: submit_video_api_v1_videos_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoSubmitRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/v1/videos/id/{video_id_path}/status:
    get:
      tags:
      - Videos
      summary: Processing status
      description: 'Return processing status for the given video.


        Accessible to the video owner (creator) or any moderator.'
      operationId: get_video_status_api_v1_videos_id__video_id_path__status_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/id/{video_id_path}:
    get:
      tags:
      - Videos
      summary: Video details
      description: Public endpoint returning full video metadata.
      operationId: get_video_details_api_v1_videos_id__video_id_path__get
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Videos
      summary: Update video details
      description: Allow owner or moderator to update title/desc/tags.
      operationId: update_video_api_v1_videos_id__video_id_path__put
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/id/{video_id_path}/view:
    post:
      tags:
      - Videos
      summary: Record playback view
      description: "Increment a video's view count.\n\nBehaviour nuances (aligned\
        \ with test-suite expectations):\n\n\u2022 If the video does **not exist**\
        \ \u2192 404 for everyone.\n\u2022 If the video exists but is **not READY**:\n\
        \    \u2013 **Unauthenticated** callers receive 404 (video hidden).\n    \u2013\
        \ Authenticated *viewer*-level callers receive 403.\n    \u2013 The owner\
        \ (*creator*) or any *moderator* can still access \u2192 404 to\n      remain\
        \ consistent with current spec (not explicitly tested yet).\n\u2022 A READY\
        \ video is public: anyone can record a view (204)."
      operationId: record_view_api_v1_videos_id__video_id_path__view_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/latest:
    get:
      tags:
      - Videos
      summary: Latest videos
      operationId: get_latest_videos_api_v1_videos_latest_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/by-tag/{tag_name}:
    get:
      tags:
      - Videos
      summary: Videos by tag
      operationId: get_videos_by_tag_api_v1_videos_by_tag__tag_name__get
      parameters:
      - name: tag_name
        in: path
        required: true
        schema:
          type: string
          title: Tag Name
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/by-uploader/{uploader_id_path}:
    get:
      tags:
      - Videos
      summary: Videos by uploader
      operationId: get_videos_by_uploader_api_v1_videos_by_uploader__uploader_id_path__get
      parameters:
      - name: uploader_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Uploader Id Path
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/id/{video_id_path}/rating:
    post:
      tags:
      - Videos
      summary: Submit rating (1-5)
      operationId: submit_rating_api_v1_videos_id__video_id_path__rating_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoRatingRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Videos
      summary: Get rating summary
      operationId: get_rating_summary_endpoint_api_v1_videos_id__video_id_path__rating_get
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoRatingSummary'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/id/{video_id_path}/related:
    get:
      tags:
      - Videos
      summary: Content-based related list
      description: 'Return a list of videos related to the given video.


        The underlying implementation is currently stubbed out and will return the

        latest videos (excluding the source video) with a random relevance score.'
      operationId: get_related_videos_for_video_api_v1_videos_id__video_id_path__related_get
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 20
          minimum: 1
          description: Max number of related videos
          default: 5
          title: Limit
        description: Max number of related videos
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecommendationItem'
                title: Response Get Related Videos For Video Api V1 Videos Id  Video
                  Id Path  Related Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/trending:
    get:
      tags:
      - Videos
      summary: Trending videos (top by views)
      description: "Return the *trending* list \u2013 most viewed videos in the selected\
        \ window."
      operationId: get_trending_videos_api_v1_videos_trending_get
      parameters:
      - name: intervalDays
        in: query
        required: false
        schema:
          type: integer
          maximum: 30
          minimum: 1
          description: Time window in days to consider (1, 7, or 30)
          examples:
            one:
              summary: 1 day
              value: 1
          default: 1
          title: Intervaldays
        description: Time window in days to consider (1, 7, or 30)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10
          minimum: 1
          description: Maximum number of records to return (max 10)
          default: 10
          title: Limit
        description: Maximum number of records to return (max 10)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VideoSummary'
                title: Response Get Trending Videos Api V1 Videos Trending Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/preview:
    post:
      tags:
      - Videos
      summary: Preview YouTube URL (title only)
      description: "Return the title of the supplied YouTube video.\n\nNo authentication\
        \ required \u2013 the client uses this to pre-fill the *Name*\nfield when\
        \ submitting a new video.  All heavy-lifting stays backend-side so\nwe avoid\
        \ CORS issues and leaking any API keys."
      operationId: preview_youtube_video_api_v1_videos_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoSubmitRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoPreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/search/videos:
    get:
      tags:
      - Search
      summary: Keyword video search
      operationId: search_videos_api_v1_search_videos_get
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          description: Search query term
          title: Query
        description: Search query term
      - name: mode
        in: query
        required: false
        schema:
          enum:
          - semantic
          - keyword
          type: string
          description: 'Search mode: semantic or keyword'
          default: keyword
          title: Mode
        description: 'Search mode: semantic or keyword'
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/search/tags/suggest:
    get:
      tags:
      - Search
      summary: Autocomplete tags
      operationId: suggest_video_tags_api_v1_search_tags_suggest_get
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          description: Partial tag to search for
          title: Query
        description: Partial tag to search for
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 25
          minimum: 1
          description: Maximum number of suggestions
          default: 10
          title: Limit
        description: Maximum number of suggestions
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TagSuggestion'
                title: Response Suggest Video Tags Api V1 Search Tags Suggest Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/{video_id_path}/comments:
    post:
      tags:
      - Comments & Ratings
      summary: Add comment to video
      description: Endpoint for viewers to add a comment to a READY video.
      operationId: post_comment_to_video_api_v1_videos__video_id_path__comments_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Comments & Ratings
      summary: List comments for video
      operationId: list_comments_video_api_v1_videos__video_id_path__comments_get
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/users/{user_id_path}/comments:
    get:
      tags:
      - Comments & Ratings
      summary: List comments by user
      operationId: list_comments_user_api_v1_users__user_id_path__comments_get
      parameters:
      - name: user_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id Path
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/videos/{video_id_path}/ratings:
    post:
      tags:
      - Comments & Ratings
      summary: Rate a video (create or update)
      description: Upsert a rating (1-5) for the specified video by the current viewer.
      operationId: post_rating_video_api_v1_videos__video_id_path__ratings_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatingCreateOrUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Comments & Ratings
      summary: Get aggregate rating plus current user's rating (optional)
      operationId: get_rating_summary_video_api_v1_videos__video_id_path__ratings_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateRatingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/recommendations/foryou:
    get:
      tags:
      - Recommendations
      summary: Personalized 'For You' video recommendations
      operationId: get_for_you_feed_api_v1_recommendations_foryou_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_VideoSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/reco/ingest:
    post:
      tags:
      - Recommendations Internal
      summary: Ingest vector embedding for a video
      description: Accept a vector embedding for a video (creator-only).
      operationId: ingest_embedding_api_v1_reco_ingest_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingIngestRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingIngestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/v1/flags:
    post:
      tags:
      - Flags
      summary: Flag content (video or comment)
      description: Create a new flag for the specified content.
      operationId: submit_flag_api_v1_flags_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlagCreateRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/v1/moderation/flags:
    get:
      tags:
      - Moderation Actions
      summary: List all flags (moderator inbox)
      operationId: list_all_flags_api_v1_moderation_flags_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/FlagStatusEnum'
          - type: 'null'
          description: Filter by flag status
          title: Status
        description: Filter by flag status
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page
          default: 10
          title: Pagesize
        description: Items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_FlagResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/moderation/flags/{flag_id_path}:
    get:
      tags:
      - Moderation Actions
      summary: Get details of a specific flag
      operationId: get_flag_details_api_v1_moderation_flags__flag_id_path__get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: flag_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Flag Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/moderation/flags/{flag_id_path}/action:
    post:
      tags:
      - Moderation Actions
      summary: Take action on a specific flag
      operationId: act_on_flag_api_v1_moderation_flags__flag_id_path__action_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: flag_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Flag Id Path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlagUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/moderation/users:
    get:
      tags:
      - Moderation Actions
      summary: Search for users (moderator only)
      operationId: search_users_endpoint_api_v1_moderation_users_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search text
          title: Q
        description: Search text
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
                title: Response Search Users Endpoint Api V1 Moderation Users Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/moderation/users/{user_id_path}/assign-moderator:
    post:
      tags:
      - Moderation Actions
      summary: Promote user to moderator
      operationId: assign_moderator_endpoint_api_v1_moderation_users__user_id_path__assign_moderator_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: user_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/moderation/users/{user_id_path}/revoke-moderator:
    post:
      tags:
      - Moderation Actions
      summary: Demote user from moderator
      operationId: revoke_moderator_endpoint_api_v1_moderation_users__user_id_path__revoke_moderator_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: user_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/moderation/videos/{video_id_path}/restore:
    post:
      tags:
      - Moderation Actions
      summary: Restore a soft-deleted video (stub)
      operationId: restore_video_endpoint_api_v1_moderation_videos__video_id_path__restore_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: video_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Video Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentRestoreResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/moderation/comments/{comment_id_path}/restore:
    post:
      tags:
      - Moderation Actions
      summary: Restore a soft-deleted comment (stub)
      operationId: restore_comment_endpoint_api_v1_moderation_comments__comment_id_path__restore_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: comment_id_path
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Comment Id Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentRestoreResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /:
    get:
      summary: Health check
      operationId: root__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    AggregateRatingResponse:
      properties:
        videoId:
          type: string
          format: uuid
          title: Videoid
        averageRating:
          anyOf:
          - type: number
          - type: 'null'
          title: Averagerating
        totalRatingsCount:
          type: integer
          title: Totalratingscount
          default: 0
        currentUserRating:
          anyOf:
          - type: integer
          - type: 'null'
          title: Currentuserrating
      type: object
      required:
      - videoId
      title: AggregateRatingResponse
    CommentCreateRequest:
      properties:
        text:
          type: string
          maxLength: 1000
          minLength: 1
          title: Text
      type: object
      required:
      - text
      title: CommentCreateRequest
      description: Payload for creating a new comment.
    CommentResponse:
      properties:
        commentid:
          type: string
          format: uuid
          title: Commentid
        videoid:
          type: string
          format: uuid
          title: Videoid
        userid:
          type: string
          format: uuid
          title: Userid
        comment:
          type: string
          title: Comment
        sentiment_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Sentiment Score
        firstName:
          anyOf:
          - type: string
          - type: 'null'
          title: Firstname
        lastName:
          anyOf:
          - type: string
          - type: 'null'
          title: Lastname
      type: object
      required:
      - commentid
      - videoid
      - userid
      - comment
      title: CommentResponse
      description: API response representation for a single comment.
    ContentRestoreResponse:
      properties:
        content_id:
          type: string
          format: uuid
          title: Content Id
        content_type:
          type: string
          title: Content Type
        status_message:
          type: string
          title: Status Message
      type: object
      required:
      - content_id
      - content_type
      - status_message
      title: ContentRestoreResponse
    ContentTypeEnum:
      type: string
      enum:
      - video
      - comment
      title: ContentTypeEnum
      description: Possible kinds of content that can be flagged.
    EmbeddingIngestRequest:
      properties:
        videoId:
          type: string
          format: uuid
          title: Videoid
        vector:
          items:
            type: number
          type: array
          title: Vector
          description: The vector embedding extracted from the video's content.
      type: object
      required:
      - videoId
      - vector
      title: EmbeddingIngestRequest
      description: "Payload accepted by the vector\u2010embedding ingestion endpoint."
    EmbeddingIngestResponse:
      properties:
        videoId:
          type: string
          format: uuid
          title: Videoid
        status:
          type: string
          title: Status
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - videoId
      - status
      title: EmbeddingIngestResponse
      description: Simple acknowledgement returned after receiving an embedding.
    FlagCreateRequest:
      properties:
        contentType:
          $ref: '#/components/schemas/ContentTypeEnum'
        contentId:
          type: string
          format: uuid
          title: Contentid
        reasonCode:
          $ref: '#/components/schemas/FlagReasonCodeEnum'
        reasonText:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reasontext
          description: Optional free-form context supplied by the reporter.
      type: object
      required:
      - contentType
      - contentId
      - reasonCode
      title: FlagCreateRequest
      description: Payload viewers submit when flagging content.
    FlagReasonCodeEnum:
      type: string
      enum:
      - spam
      - inappropriate
      - harassment
      - copyright
      - other
      title: FlagReasonCodeEnum
      description: Standardized reasons a user can provide when flagging content.
    FlagResponse:
      properties:
        contentType:
          $ref: '#/components/schemas/ContentTypeEnum'
        contentId:
          type: string
          format: uuid
          title: Contentid
        reasonCode:
          $ref: '#/components/schemas/FlagReasonCodeEnum'
        reasonText:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reasontext
          description: Optional free-form context supplied by the reporter.
        flagId:
          type: string
          format: uuid
          title: Flagid
        userId:
          type: string
          format: uuid
          title: Userid
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        status:
          $ref: '#/components/schemas/FlagStatusEnum'
          default: open
        moderatorId:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Moderatorid
        moderatorNotes:
          anyOf:
          - type: string
          - type: 'null'
          title: Moderatornotes
        resolvedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Resolvedat
      type: object
      required:
      - contentType
      - contentId
      - reasonCode
      - userId
      - createdAt
      - updatedAt
      title: FlagResponse
      description: Alias used in API responses.
    FlagStatusEnum:
      type: string
      enum:
      - open
      - under_review
      - approved
      - rejected
      title: FlagStatusEnum
      description: Lifecycle states for the moderation flag itself.
    FlagUpdateRequest:
      properties:
        status:
          $ref: '#/components/schemas/FlagStatusEnum'
        moderatorNotes:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: Moderatornotes
      type: object
      required:
      - status
      title: FlagUpdateRequest
      description: Payload moderators send when changing a flag's status.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PaginatedResponse:
      properties:
        data:
          items: {}
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/Pagination'
      type: object
      required:
      - data
      - pagination
      title: PaginatedResponse
    PaginatedResponse_FlagResponse_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/FlagResponse'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/Pagination'
      type: object
      required:
      - data
      - pagination
      title: PaginatedResponse[FlagResponse]
    PaginatedResponse_VideoSummary_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/VideoSummary'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/Pagination'
      type: object
      required:
      - data
      - pagination
      title: PaginatedResponse[VideoSummary]
    Pagination:
      properties:
        currentPage:
          type: integer
          title: Currentpage
        pageSize:
          type: integer
          title: Pagesize
        totalItems:
          type: integer
          title: Totalitems
        totalPages:
          type: integer
          title: Totalpages
      type: object
      required:
      - currentPage
      - pageSize
      - totalItems
      - totalPages
      title: Pagination
    RatingCreateOrUpdateRequest:
      properties:
        rating:
          type: integer
          maximum: 5.0
          minimum: 1.0
          title: Rating
          description: Rating value 1-5
      type: object
      required:
      - rating
      title: RatingCreateOrUpdateRequest
    RatingResponse:
      properties:
        rating:
          type: integer
          maximum: 5.0
          minimum: 1.0
          title: Rating
          description: Rating value 1-5
        videoid:
          type: string
          format: uuid
          title: Videoid
        userid:
          type: string
          format: uuid
          title: Userid
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - rating
      - videoid
      - userid
      title: RatingResponse
    RecommendationItem:
      properties:
        videoId:
          type: string
          format: uuid
          title: Videoid
        title:
          type: string
          title: Title
        thumbnailUrl:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Thumbnailurl
        score:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Score
          description: Relevance score where 1 is most relevant.
      type: object
      required:
      - videoId
      - title
      title: RecommendationItem
      description: Lightweight representation of a recommended video for list endpoints.
    TagSuggestion:
      properties:
        tag:
          type: string
          title: Tag
      type: object
      required:
      - tag
      title: TagSuggestion
    User:
      properties:
        firstName:
          type: string
          maxLength: 50
          minLength: 1
          title: Firstname
        lastName:
          type: string
          maxLength: 50
          minLength: 1
          title: Lastname
        email:
          type: string
          format: email
          title: Email
        userId:
          type: string
          format: uuid
          title: Userid
        createdDate:
          type: string
          format: date-time
          title: Createddate
        accountStatus:
          type: string
          title: Accountstatus
          default: active
        lastLoginDate:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Lastlogindate
        roles:
          items:
            type: string
          type: array
          title: Roles
          default: []
      type: object
      required:
      - firstName
      - lastName
      - email
      - userId
      title: User
    UserCreateRequest:
      properties:
        firstName:
          type: string
          maxLength: 50
          minLength: 1
          title: Firstname
        lastName:
          type: string
          maxLength: 50
          minLength: 1
          title: Lastname
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          minLength: 8
          title: Password
      type: object
      required:
      - firstName
      - lastName
      - email
      - password
      title: UserCreateRequest
    UserCreateResponse:
      properties:
        firstName:
          type: string
          maxLength: 50
          minLength: 1
          title: Firstname
        lastName:
          type: string
          maxLength: 50
          minLength: 1
          title: Lastname
        email:
          type: string
          format: email
          title: Email
        userId:
          type: string
          format: uuid
          title: Userid
      type: object
      required:
      - firstName
      - lastName
      - email
      - userId
      title: UserCreateResponse
    UserLoginRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          minLength: 1
          title: Password
      type: object
      required:
      - email
      - password
      title: UserLoginRequest
    UserLoginResponse:
      properties:
        token:
          type: string
          title: Token
        user:
          $ref: '#/components/schemas/User'
      type: object
      required:
      - token
      - user
      title: UserLoginResponse
    UserProfileUpdateRequest:
      properties:
        firstName:
          anyOf:
          - type: string
            maxLength: 50
            minLength: 1
          - type: 'null'
          title: Firstname
        lastName:
          anyOf:
          - type: string
            maxLength: 50
            minLength: 1
          - type: 'null'
          title: Lastname
      type: object
      title: UserProfileUpdateRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VideoDetailResponse:
      properties:
        title:
          type: string
          maxLength: 100
          minLength: 3
          title: Title
        description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Description
        tags:
          items:
            type: string
          type: array
          title: Tags
        videoId:
          type: string
          format: uuid
          title: Videoid
        userId:
          type: string
          format: uuid
          title: Userid
        submittedAt:
          type: string
          format: date-time
          title: Submittedat
        thumbnailUrl:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Thumbnailurl
        location:
          type: string
          title: Location
        location_type:
          type: integer
          title: Location Type
        content_features:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Content Features
        content_rating:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Rating
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        youtubeVideoId:
          anyOf:
          - type: string
          - type: 'null'
          title: Youtubevideoid
        updatedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updatedat
        status:
          $ref: '#/components/schemas/VideoStatusEnum'
          default: PENDING
        views:
          type: integer
          title: Views
          default: 0
        averageRating:
          anyOf:
          - type: number
          - type: 'null'
          title: Averagerating
        totalRatingsCount:
          type: integer
          title: Totalratingscount
          default: 0
        is_deleted:
          type: boolean
          title: Is Deleted
          default: false
        deleted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deleted At
      type: object
      required:
      - title
      - userId
      - submittedAt
      - location
      - location_type
      title: VideoDetailResponse
      description: Response model returned when fetching full video details.
    VideoPreviewResponse:
      properties:
        title:
          type: string
          title: Title
      type: object
      required:
      - title
      title: VideoPreviewResponse
      description: Response model used by the *preview* endpoint to pre-fill UI fields.
    VideoRatingRequest:
      properties:
        rating:
          type: integer
          maximum: 5.0
          minimum: 1.0
          title: Rating
      type: object
      required:
      - rating
      title: VideoRatingRequest
      description: Client payload for submitting a rating (1-5).
    VideoRatingSummary:
      properties:
        videoId:
          type: string
          format: uuid
          title: Videoid
        averageRating:
          type: number
          title: Averagerating
        ratingCount:
          type: integer
          title: Ratingcount
      type: object
      required:
      - videoId
      - averageRating
      - ratingCount
      title: VideoRatingSummary
      description: Aggregated rating stats for a video.
    VideoStatusEnum:
      type: string
      enum:
      - PENDING
      - PROCESSING
      - READY
      - ERROR
      title: VideoStatusEnum
      description: Possible processing states for a submitted video.
    VideoStatusResponse:
      properties:
        videoId:
          type: string
          format: uuid
          title: Videoid
        status:
          $ref: '#/components/schemas/VideoStatusEnum'
      type: object
      required:
      - videoId
      - status
      title: VideoStatusResponse
      description: Response model that surfaces only the processing status.
    VideoSubmitRequest:
      properties:
        youtubeUrl:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Youtubeurl
        title:
          anyOf:
          - type: string
            maxLength: 150
            minLength: 1
          - type: 'null'
          title: Title
          description: Optional video title obtained from the preview step.
      type: object
      required:
      - youtubeUrl
      title: VideoSubmitRequest
      description: "Payload accepted by the *submit video* endpoint.\n\nThe **title**\
        \ is optional \u2013 if the client already looked it up via the\npreview endpoint\
        \ it can pass it here so the user immediately sees the\ncorrect name instead\
        \ of the temporary placeholder."
    VideoSummary:
      properties:
        videoId:
          type: string
          format: uuid
          title: Videoid
        title:
          type: string
          title: Title
        thumbnailUrl:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Thumbnailurl
        userId:
          type: string
          format: uuid
          title: Userid
        submittedAt:
          type: string
          format: date-time
          title: Submittedat
        content_rating:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Rating
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        views:
          type: integer
          title: Views
          default: 0
        averageRating:
          anyOf:
          - type: number
          - type: 'null'
          title: Averagerating
      type: object
      required:
      - videoId
      - title
      - userId
      - submittedAt
      title: VideoSummary
      description: Smaller representation used in paginated lists (e.g., latest videos).
    VideoUpdateRequest:
      properties:
        title:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 3
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Description
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
      type: object
      title: VideoUpdateRequest
      description: Payload for partial updates to a video owned by the caller or a
        moderator.
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/users/login