openapi: 3.1.0
info:
  title: Piggyback Learning
  version: 0.1.0
paths:
  /api/kids_videos:
    get:
      summary: List Kids Videos
      description: Return JSON of all locally available kids videos
      operationId: list_kids_videos_api_kids_videos_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/final-questions/{video_id}:
    get:
      summary: Get Final Questions
      description: |-
        Loads final_questions.json for the given video_id.
        Returns the best LLM-ranked question per segment (lowest llm_ranking)
        that is not trashed. If trashed=True, skip to the next question.
      operationId: get_final_questions_api_final_questions__video_id__get
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            title: Video Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/check_answer:
    post:
      summary: Check Answer
      operationId: check_answer_api_check_answer_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/transcribe:
    post:
      summary: Transcribe Audio
      description: |-
        Accepts audio (webm, wav, mp3, etc), sends to Whisper,
        no temp file saved (in-memory BytesIO).
      operationId: transcribe_audio_api_transcribe_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_transcribe_audio_api_transcribe_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/config:
    get:
      summary: Get Config
      operationId: get_config_api_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /admin/:
    get:
      summary: Admin Page
      operationId: admin_page_admin__get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
  /api/download:
    post:
      summary: Api Download
      operationId: api_download_api_download_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_api_download_api_download_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/frames/{video_id}:
    post:
      summary: Api Extract Frames
      operationId: api_extract_frames_api_frames__video_id__post
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            title: Video Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/videos:
    get:
      summary: Admin List Downloaded Videos
      description: >-
        Provide a lightweight manifest of downloaded videos so admins can reuse
        them.
      operationId: admin_list_downloaded_videos_api_admin_videos_get
      parameters:
        - name: include_without_frames
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Without Frames
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/submit-questions:
    post:
      summary: Submit Questions
      description: |-
        Submit and save finalized questions (admin 'Submit' in UI).
        Saves to downloads/<video_id>/questions/<video_id>.json
      operationId: submit_questions_api_submit_questions_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /:
    get:
      summary: Home Page
      description: Home page with user type selection
      operationId: home_page__get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
  /home:
    get:
      summary: Home Redirect
      description: Alternative home page route
      operationId: home_redirect_home_get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
  /children:
    get:
      summary: Children Page
      description: Children's learning interface - no password required
      operationId: children_page_children_get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
  /api/verify-password:
    post:
      summary: Verify Password
      description: Verify password for admin/expert access
      operationId: verify_password_api_verify_password_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: >-
                #/components/schemas/Body_verify_password_api_verify_password_post
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /expert-preview:
    get:
      summary: Expert Preview
      operationId: expert_preview_expert_preview_get
      parameters:
        - name: file
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: File
        - name: video
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Video
        - name: mode
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: review
            title: Mode
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/expert-annotations:
    post:
      summary: Save Expert Annotation
      operationId: save_expert_annotation_api_expert_annotations_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos-list:
    get:
      summary: List Videos
      description: >-
        List all downloaded videos with title, thumbnail, duration, and question
        counts.
      operationId: list_videos_api_videos_list_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/expert-questions/{video_id}:
    get:
      summary: Get Expert Questions
      operationId: get_expert_questions_api_expert_questions__video_id__get
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
            title: Video Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/expert-questions:
    post:
      summary: Save Expert Question
      operationId: save_expert_question_api_expert_questions_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/save-final-questions:
    post:
      summary: Save Final Questions
      description: Save final reviewed questions to a dedicated folder
      operationId: save_final_questions_api_save_final_questions_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tts:
    post:
      summary: Synthesize Tts
      description: Generate speech audio via OpenAI TTS.
      operationId: synthesize_tts_api_tts_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_api_download_api_download_post:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
        - url
      title: Body_api_download_api_download_post
    Body_transcribe_audio_api_transcribe_post:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
        - file
      title: Body_transcribe_audio_api_transcribe_post
    Body_verify_password_api_verify_password_post:
      properties:
        user_type:
          type: string
          title: User Type
        password:
          type: string
          title: Password
      type: object
      required:
        - user_type
        - password
      title: Body_verify_password_api_verify_password_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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