openapi: 3.0.3
info:
  title: Global Football Quiz REST API
  description: Authoritative backend API for the Global Football Quiz mobile application.
  version: 1.0.0
servers:
  - url: http://localhost:8000/api/v1
    description: Local Development Server
paths:
  /auth/register:
    post:
      summary: Register a new player
      tags: [Authentication]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email, password]
              properties:
                name: { type: string, example: "Alex Striker" }
                display_name: { type: string, example: "AlexStriker9" }
                email: { type: string, format: email, example: "striker@globalfootballquiz.com" }
                password: { type: string, format: password, minLength: 8 }
                country_code: { type: string, example: "GBR" }
                favorite_club: { type: string, example: "Arsenal FC" }
      responses:
        '201':
          description: Registered successfully
  /auth/login:
    post:
      summary: Player login
      tags: [Authentication]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string, format: password }
      responses:
        '200':
          description: Logged in successfully with bearer token
  /me:
    get:
      summary: Get authenticated player profile and stats
      tags: [Player Profile]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Player profile details
  /categories:
    get:
      summary: List all active football categories
      tags: [Discovery]
      responses:
        '200':
          description: List of categories with question counts
  /daily-challenges/current:
    get:
      summary: Get today's featured daily football challenge
      tags: [Discovery]
      responses:
        '200':
          description: Daily challenge details
  /leaderboards/global:
    get:
      summary: Retrieve global rankings leaderboard
      tags: [Progression & Rankings]
      responses:
        '200':
          description: Top players sorted by XP
  /quiz-sessions:
    post:
      summary: Start a new authoritative quiz session
      tags: [Solo Quiz Engine]
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                category_slug: { type: string, example: "fifa-world-cup" }
                mode: { type: string, enum: [solo_standard, solo_timed, daily_challenge, practice] }
                difficulty: { type: string, enum: [easy, medium, hard, mixed] }
                question_count: { type: integer, default: 5 }
      responses:
        '201':
          description: Quiz session created
  /quiz-sessions/{id}/questions/current:
    get:
      summary: Get active question without answer leaks
      tags: [Solo Quiz Engine]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Question prompt and options (is_correct hidden)
  /quiz-sessions/{id}/answers:
    post:
      summary: Submit authoritative answer for scoring
      tags: [Solo Quiz Engine]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [option_id]
              properties:
                option_id: { type: integer }
                time_spent_ms: { type: integer }
      responses:
        '200':
          description: Feedback with points awarded and explanation
  /quiz-sessions/{id}/advance:
    post:
      summary: Advance to next question or complete session
      tags: [Solo Quiz Engine]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Next index or completion state
  /quiz-sessions/{id}/results:
    get:
      summary: Retrieve comprehensive match results and breakdown
      tags: [Solo Quiz Engine]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Full post-match review
  /question-packs:
    get:
      summary: List available question packs for offline play
      tags: [Question Packs]
      responses:
        '200':
          description: List of question packs
  /question-packs/{id}/download:
    get:
      summary: Download pack questions with SHA256 checksum verification
      tags: [Question Packs]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Pack payload with sha256 checksum
  /multiplayer/matchmaking/join:
    post:
      summary: Join matchmaking queue for 1v1 duel
      tags: [Multiplayer Engine]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Match found or queued for searching
  /multiplayer/matches/create-private:
    post:
      summary: Create private room with 6-char invite code
      tags: [Multiplayer Engine]
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Private lobby created
  /multiplayer/matches/join-private:
    post:
      summary: Join private room via invite code
      tags: [Multiplayer Engine]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Joined private duel
  /multiplayer/matches/{id}/questions:
    get:
      summary: Fetch questions for match with options masked
      tags: [Multiplayer Engine]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Masked questions for duel round
  /multiplayer/matches/{id}/answers:
    post:
      summary: Authoritative answer submission for duel round
      tags: [Multiplayer Engine]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Authoritative scoring, speed bonus, and live scores
  /multiplayer/leaderboard/rating:
    get:
      summary: Global Elo rating leaderboard
      tags: [Multiplayer Engine]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Leaderboard rankings
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SanctumToken