admin-openapi.yaml

openapi: 3.0.0
info:
  title: Culturae API
  description: Complete API documentation for Culturae administration and management.
  version: 1.0.0
  x-last-updated: "2026-04-26"
servers:
- url: https://demo.culturae.me
  description: Production
- url: http://localhost:8080
  description: Local Development Backend Server
- url: http://localhost:80
  description: Local Development with Docker
security:
- BearerAuth: []
tags:
- name: System
  description: System health and status
- name: Auth
  description: Authentication endpoints
- name: Profile
  description: User profile management
- name: Avatar
  description: User avatar management
- name: Users
  description: Public user search and details
- name: Friends
  description: Friend request and friendship management
- name: Games
  description: Game creation and gameplay
- name: Realtime
  description: Real-time WebSocket connection for online presence, game events, and notifications
- name: Admin Users
  description: User management for admins
- name: Admin Avatar
  description: Avatar management for admins
- name: Admin Logs
  description: System and user logs
- name: Admin Questions
  description: Question management
- name: Admin Friends
  description: Friendship management for admins
- name: Admin Imports
  description: Data import jobs
- name: Admin Datasets
  description: Dataset management
- name: Admin Geography
  description: Geography dataset management for admins
- name: Admin Games
  description: Game management for admins
- name: Admin Reports
  description: Management of user-submitted reports
- name: Admin Matchmaking
  description: Management of matchmaking queues
- name: Admin Settings
  description: System settings (maintenance mode, rate limiting, cache)
- name: Admin Game Templates
  description: Game template management for admins
- name: Admin Pods
  description: Pod discovery and multi-instance monitoring
- name: Geography
  description: Public geography data (countries, continents, regions, flags)
- name: Reports
  description: Question reporting (user-facing)
- name: Notifications
  description: User notification management (game invites, friend requests, etc.)
- name: Leaderboard
  description: Global and mode-specific player rankings
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    Forbidden:
      description: Forbidden – authenticated but not allowed to access this resource.
      content:
        application/json:
          schema: &id001
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
          example:
            error:
              code: FORBIDDEN
              message: admin access required
    Unauthorized:
      description: Unauthorized – missing or invalid authentication token.
      content:
        application/json:
          schema: *id001
          example:
            error:
              code: UNAUTHORIZED
              message: authentication required
    NotFound:
      description: Not Found – the requested resource does not exist.
      content:
        application/json:
          schema: *id001
          example:
            error:
              code: NOT_FOUND
              message: resource not found
    BadRequest:
      description: Bad Request – validation error or malformed body.
      content:
        application/json:
          schema: *id001
          example:
            error:
              code: BAD_REQUEST
              message: invalid request body
    InternalServerError:
      description: Internal Server Error – unexpected server-side failure.
      content:
        application/json:
          schema: *id001
          example:
            error:
              code: INTERNAL_ERROR
              message: internal server error
    TooManyRequests:
      description: Too Many Requests – rate limit exceeded.
      content:
        application/json:
          schema: *id001
          example:
            error:
              code: RATE_LIMITED
              message: too many requests, please slow down
  parameters:
    limit:
      name: limit
      in: query
      description: Max number of items to return (pagination)
      schema:
        type: integer
        format: int32
        default: 50
        minimum: 1
        maximum: 1000
    offset:
      name: offset
      in: query
      description: Offset for pagination (use with limit)
      schema:
        type: integer
        format: int32
        default: 0
        minimum: 0
    page:
      name: page
      in: query
      description: Page number for pagination (alternative to offset)
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    status:
      name: status
      in: query
      description: Filter by status (semantics depend on endpoint, e.g., 'online'|'offline' or 'pending'|'accepted')
      schema:
        type: string
    user_status:
      name: status
      in: query
      description: Online status for users
      schema:
        type: string
        enum:
        - online
        - offline
    friend_request_status:
      name: status
      in: query
      description: Status for friend requests
      schema:
        type: string
        enum:
        - pending
        - accepted
        - rejected
        - blocked
    game_status:
      name: status
      in: query
      description: Status for games
      schema:
        type: string
        enum:
        - waiting
        - ready
        - in_progress
        - completed
        - cancelled
        - abandoned
    game_invite_status:
      name: status
      in: query
      description: Status for game invites
      schema:
        type: string
        enum:
        - pending
        - accepted
        - rejected
        - cancelled
    role:
      name: role
      in: query
      description: Filter users by role
      schema:
        type: string
    level:
      name: level
      in: query
      description: Filter users by level (numeric)
      schema:
        type: integer
        format: int32
        minimum: 0
    rank:
      name: rank
      in: query
      description: Filter users by rank name (Beginner, Intermediate, Expert, Master)
      schema:
        type: string
    account_status:
      name: account_status
      in: query
      description: Filter users by account status (active, suspended, banned, inactive)
      schema:
        type: string
        enum:
        - active
        - suspended
        - banned
        - inactive
    query:
      name: query
      in: query
      description: Free-text search query
      schema:
        type: string
    search:
      name: search
      in: query
      description: Search text (for questions endpoint)
      schema:
        type: string
    dataset_id:
      name: dataset_id
      in: query
      description: Dataset UUID filter
      schema:
        type: string
        format: uuid
    user_id:
      name: user_id
      in: query
      description: User UUID filter
      schema:
        type: string
        format: uuid
    days:
      name: days
      in: query
      description: Number of days to include in the statistic
      schema:
        type: integer
        format: int32
        default: 30
        minimum: 1
    mode:
      name: mode
      in: query
      description: Filter by game mode
      schema:
        type: string
        enum:
        - solo
        - 1v1
    type:
      name: type
      in: query
      description: Dataset or import type filter
      schema:
        type: string
        enum:
        - questions
        - geography
    active_only:
      name: active_only
      in: query
      description: When true, return only active datasets
      schema:
        type: boolean
        default: false
    include_hash:
      name: include_hash
      in: query
      description: Include password hashes in export (for migration)
      schema:
        type: boolean
        default: false
    date_from:
      name: date_from
      in: query
      description: Start date (inclusive) for date range filters (ISO 8601)
      schema:
        type: string
        format: date-time
    date_to:
      name: date_to
      in: query
      description: End date (inclusive) for date range filters (ISO 8601)
      schema:
        type: string
        format: date-time
    start_date:
      name: start_date
      in: query
      description: Start date (inclusive) for date range filters (ISO 8601) — alias used by some endpoints
      schema:
        type: string
        format: date-time
    end_date:
      name: end_date
      in: query
      description: End date (inclusive) for date range filters (ISO 8601) — alias used by some endpoints
      schema:
        type: string
        format: date-time
    action:
      name: action
      in: query
      description: Action name to filter logs
      schema:
        type: string
    admin_id:
      name: admin_id
      in: query
      description: Filter logs by admin UUID
      schema:
        type: string
        format: uuid
    is_success:
      name: is_success
      in: query
      description: Filter by success flag (boolean)
      schema:
        type: boolean
    is_error:
      name: is_error
      in: query
      description: Filter by error flag (boolean)
      schema:
        type: boolean
    success:
      name: success
      in: query
      description: Filter by success flag (boolean) (used in connection logs)
      schema:
        type: boolean
    method:
      name: method
      in: query
      description: HTTP method to filter logs (GET, POST, etc.)
      schema:
        type: string
        enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
    path:
      name: path
      in: query
      description: Request path to filter logs
      schema:
        type: string
    status_code:
      name: status_code
      in: query
      description: HTTP status code to filter API request logs
      schema:
        type: integer
        format: int32
    continent:
      name: continent
      in: query
      description: Continent filter for geography datasets
      schema:
        type: string
    region:
      name: region
      in: query
      description: Region filter for geography datasets
      schema:
        type: string
    driving_side:
      name: driving_side
      in: query
      description: Driving side filter (e.g., left, right)
      schema:
        type: string
    population_min:
      name: population_min
      in: query
      description: Minimum population filter
      schema:
        type: integer
        format: int64
    population_max:
      name: population_max
      in: query
      description: Maximum population filter
      schema:
        type: integer
        format: int64
    area_min:
      name: area_min
      in: query
      description: Minimum area filter (km²)
      schema:
        type: number
        format: double
    area_max:
      name: area_max
      in: query
      description: Maximum area filter (km²)
      schema:
        type: number
        format: double
    un_member:
      name: un_member
      in: query
      description: Filter by UN member status (true/false)
      schema:
        type: boolean
    source:
      name: source
      in: query
      description: Source URL for import endpoints (or use JSON body param 'url')
      schema:
        type: string
    q:
      name: q
      in: query
      description: Free-text query (short form)
      schema:
        type: string
  schemas:
    PodInfo:
      type: object
      description: Real-time snapshot of a running pod, published via Redis heartbeat every 5 seconds.
      required:
      - pod_id
      - pod_type
      - status
      - is_current
      - connected_clients
      - online_users
      - active_games
      - last_heartbeat
      - started_at
      properties:
        pod_id:
          type: string
          format: uuid
          description: Unique identifier assigned at pod startup.
          example: 3f6a1b2c-dead-beef-0000-aabbccddeeff
        pod_type:
          type: string
          enum: [main, headless]
          description: |
            `main` — serves both REST and WebSocket traffic.
            `headless` — background worker pod (game engine, matchmaking); no WebSocket clients.
        status:
          type: string
          enum: [healthy, degraded, offline]
          description: Self-reported health status included in the heartbeat payload.
        is_current:
          type: boolean
          description: "`true` when this pod handled the current HTTP request."
        connected_clients:
          type: integer
          format: int64
          minimum: 0
          description: Number of open WebSocket connections on this pod (0 for headless pods).
        online_users:
          type: integer
          format: int64
          minimum: 0
          description: Number of distinct authenticated users connected via WebSocket on this pod.
        active_games:
          type: integer
          format: int64
          minimum: 0
          description: Number of in-progress or waiting games managed by this pod.
        last_heartbeat:
          type: string
          format: date-time
          description: Timestamp of the most recent heartbeat published to Redis (RFC 3339).
        started_at:
          type: string
          format: date-time
          description: Timestamp when the pod process started (RFC 3339).
    PodsMeta:
      type: object
      description: Aggregated counters across all discovered pods.
      required:
      - total_pods
      - main_pods
      - headless_pods
      - total_clients
      - total_users
      properties:
        total_pods:
          type: integer
          format: int64
          minimum: 0
          description: Total number of live pods (heartbeat TTL not expired).
        main_pods:
          type: integer
          format: int64
          minimum: 0
          description: Number of pods with `pod_type: main`.
        headless_pods:
          type: integer
          format: int64
          minimum: 0
          description: Number of pods with `pod_type: headless`.
        total_clients:
          type: integer
          format: int64
          minimum: 0
          description: Sum of `connected_clients` across all pods.
        total_users:
          type: integer
          format: int64
          minimum: 0
          description: Sum of `online_users` across all pods.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              additionalProperties: true
              nullable: true
              description: Additional error details
    RegisterRequest:
      type: object
      required:
      - email
      - username
      - password
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        username:
          type: string
          minLength: 3
          maxLength: 20
          pattern: ^[a-zA-Z0-9\-]+$
          description: 3–20 characters, letters, numbers and hyphens only
          example: player123
        password:
          type: string
          minLength: 8
          format: password
          description: 'Minimum 8 characters. Must contain at least one uppercase letter, one digit, and one special character.

            '
          example: SecurePass1!
    LoginRequest:
      type: object
      required:
      - identifier
      - password
      properties:
        identifier:
          type: string
          description: Email address or username
          example: user@example.com
        password:
          type: string
          format: password
    RefreshTokenRequest:
      type: object
      properties:
        refresh_token:
          type: string
          description: 'Refresh token obtained from login/register. Optional if the `culturae_refresh` HttpOnly cookie is
            present — the server will use the cookie as fallback.

            '
      description: 'Either `refresh_token` in the body or the `culturae_refresh` HttpOnly cookie must be present.

        '
    SessionResponse:
      type: object
      description: 'Session payload returned by login, register, login-admin and refresh endpoints. Tokens are also set as
        HttpOnly cookies (`culturae_token` for the access token, `culturae_refresh` for the refresh token).

        '
      required:
      - token
      - refresh_token
      - expires_at
      - token_expires_at
      - user
      properties:
        created:
          type: string
          format: date-time
          description: Session creation timestamp
        token:
          type: string
          description: 'Short-lived JWT access token (15 min default, 10 min in production). Send as `Authorization: Bearer
            <token>` header, or rely on the `culturae_token` HttpOnly cookie set by the server.

            '
        refresh_token:
          type: string
          description: 'Long-lived opaque refresh token (30 days default, 60 days in production). **Rotated on every call
            to `/auth/refresh`** — always store the latest value. Stored in the `culturae_refresh` HttpOnly cookie automatically.

            '
        expires_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds) when the **refresh token** expires
        token_expires_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds) when the **access token** expires
        user:
          $ref: '#/components/schemas/PublicUser'
    PublicUser:
      type: object
      description: Minimal user info returned in auth responses
      properties:
        public_id:
          type: string
          description: Short public identifier (not a UUID)
          example: '#20483-18393'
        username:
          type: string
          example: player123
        email:
          type: string
          format: email
          example: user@example.com
        language:
          type: string
          example: fr
        role:
          type: string
          enum:
          - user
          - moderator
          - administrator
          example: user
    AuthResponse:
      type: object
      description: 'Envelope returned by register, login, login-admin and refresh endpoints. On success the server also sets
        `culturae_auth` (access token) and `culturae_refresh` (refresh token) as HttpOnly, Secure, SameSite=Strict cookies
        in addition to returning the tokens in the response body.

        '
      properties:
        message:
          type: string
          example: Login successful
        data:
          $ref: '#/components/schemas/SessionResponse'
      example:
        message: Login successful
        data:
          created: '2025-12-15T12:00:00Z'
          token: ey...
          refresh_token: rftk_...
          expires_at: 1700000000
          token_expires_at: 1700003600
          user:
            public_id: '#20483-18393'
            username: player123
            email: user@example.com
            language: fr
            role: user
    User:
      type: object
      description: 'Full user object returned by the user-facing profile endpoint. Internal UUID is hidden (`json:"-"` in
        Go model).

        '
      properties:
        email:
          type: string
          format: email
        username:
          type: string
        public_id:
          type: string
          example: '#20483-18393'
        role:
          type: string
          enum:
          - user
          - moderator
          - administrator
        level:
          type: integer
          example: 5
        rank:
          type: string
          example: Beginner
        account_status:
          type: string
          enum:
          - active
          - suspended
          - banned
          - inactive
          - deleted
        banned_until:
          type: string
          format: date-time
          nullable: true
        ban_reason:
          type: string
          nullable: true
        has_avatar:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        country:
          type: string
          nullable: true
        bio:
          type: string
          nullable: true
        language:
          type: string
          example: fr
        experience:
          type: integer
          format: int64
        elo_rating:
          type: integer
          description: ELO rating for ranked matches
          example: 1000
        elo_games_played:
          type: integer
          example: 0
        status:
          type: string
          enum:
          - online
          - offline
        is_online:
          type: boolean
        last_seen_at:
          type: string
          format: date-time
          nullable: true
        current_game_id:
          type: string
          format: uuid
          nullable: true
        is_profile_public:
          type: boolean
        show_online_status:
          type: boolean
        allow_friend_requests:
          type: boolean
        allow_party_invites:
          type: boolean
        last_public_id_regeneration:
          type: string
          format: date-time
          nullable: true
        game_stats:
          nullable: true
          $ref: '#/components/schemas/UserGameStats'
    AdminUser:
      type: object
      description: 'Full user object returned by admin endpoints. Includes the internal UUID `id` field (exposed only to administrators).

        '
      properties:
        id:
          type: string
          format: uuid
          description: Internal UUID (admin-only)
        email:
          type: string
          format: email
        username:
          type: string
        public_id:
          type: string
          example: '#20483-18393'
        role:
          type: string
          enum:
          - user
          - moderator
          - administrator
        account_status:
          type: string
          enum:
          - active
          - suspended
          - banned
          - inactive
          - deleted
        banned_until:
          type: string
          format: date-time
          nullable: true
        ban_reason:
          type: string
          nullable: true
        has_avatar:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        country:
          type: string
          nullable: true
        bio:
          type: string
          nullable: true
        language:
          type: string
          example: fr
        experience:
          type: integer
          format: int64
        level:
          type: integer
          example: 5
        rank:
          type: string
          example: Beginner
        elo_rating:
          type: integer
          example: 1000
        elo_games_played:
          type: integer
          example: 0
        status:
          type: string
          enum:
          - online
          - offline
        is_online:
          type: boolean
        last_seen_at:
          type: string
          format: date-time
          nullable: true
        current_game_id:
          type: string
          format: uuid
          nullable: true
        is_profile_public:
          type: boolean
        show_online_status:
          type: boolean
        allow_friend_requests:
          type: boolean
        allow_party_invites:
          type: boolean
        game_stats:
          nullable: true
          $ref: '#/components/schemas/UserGameStats'
    UserGameStats:
      type: object
      description: Aggregate game statistics for a user
      properties:
        total_games:
          type: integer
        games_won:
          type: integer
        games_lost:
          type: integer
        day_streak:
          type: integer
          description: Current daily activity streak
        best_day_streak:
          type: integer
        total_score:
          type: integer
          format: int64
        average_score:
          type: number
        play_time:
          type: integer
          format: int64
          description: Total play time in seconds
        last_game_at:
          type: string
          format: date-time
          nullable: true
    UserUpdate:
      type: object
      description: 'Fields that can be updated by an admin. All fields are optional. `language` must be one of: `en`, `fr`,
        `es`. `bio` max 50 characters. When `account_status` is set to `inactive` or `banned`, all user sessions are automatically
        revoked.

        '
      properties:
        email:
          type: string
          format: email
        username:
          type: string
          minLength: 3
          maxLength: 20
        role:
          type: string
          enum:
          - user
          - moderator
          - administrator
        account_status:
          type: string
          enum:
          - active
          - suspended
          - banned
          - inactive
          description: Cannot be set to `deleted` via this endpoint
        bio:
          type: string
          maxLength: 50
          nullable: true
        language:
          type: string
          enum:
          - en
          - fr
          - es
        is_profile_public:
          type: boolean
        show_online_status:
          type: boolean
        allow_friend_requests:
          type: boolean
        allow_party_invites:
          type: boolean
    UserBasicInfo:
      type: object
      description: 'Minimal user info returned by `GET /me`. Sufficient for navbar and lightweight UI components.

        Also used by mobile clients on startup to detect an in-progress game via

        `current_game_public_id` and auto-redirect the player back into it.

        '
      properties:
        public_id:
          type: string
          example: '#20483-18393'
        username:
          type: string
          example: player123
        has_avatar:
          type: boolean
        language:
          type: string
          example: en
        role:
          type: string
          example: user
        level:
          type: integer
          description: Numeric level
        rank:
          type: string
          description: Named rank tier (e.g. bronze, silver, gold)
        elo_rating:
          type: integer
        current_game_public_id:
          type: string
          nullable: true
          description: 'Public ID of the game the user is currently playing.

            Present only when the user has an active (in-progress or waiting) game.

            Clients should use this on startup to detect a resumed session and

            redirect back into the game automatically.

            '
          example: gm-a1b2c3d4
    PublicProfile:
      type: object
      description: 'Public-facing profile of a user. No internal UUID exposed. Respects privacy settings (`show_online_status`,
        etc.).

        '
      properties:
        public_id:
          type: string
          example: '#20483-18393'
        username:
          type: string
        has_avatar:
          type: boolean
        created_at:
          type: string
          format: date-time
        country:
          type: string
          nullable: true
        bio:
          type: string
          nullable: true
        language:
          type: string
        level:
          type: integer
          example: 5
        rank:
          type: string
          example: Beginner
        status:
          type: string
          enum:
          - online
          - offline
        play_time:
          type: integer
          format: int64
          description: Total play time in seconds
        total_games:
          type: integer
        games_won:
          type: integer
        games_lost:
          type: integer
        day_streak:
          type: integer
          description: Current daily activity streak
        best_day_streak:
          type: integer
        total_score:
          type: integer
          format: int64
        average_score:
          type: number
        last_game_at:
          type: string
          format: date-time
          nullable: true
        elo_rating:
          type: integer
          example: 1000
        elo_games_played:
          type: integer
        experience:
          type: integer
          format: int64
        is_online:
          type: boolean
        show_online_status:
          type: boolean
        last_seen_at:
          type: string
          format: date-time
          nullable: true
        allow_friend_requests:
          type: boolean
    UserProfileWithRelationship:
      type: object
      description: 'Public profile enriched with relationship context for the authenticated viewer. Returned by `GET /api/v1/users/profile/{publicID}`.

        '
      allOf:
      - $ref: '#/components/schemas/PublicProfile'
      - type: object
        properties:
          is_friend:
            type: boolean
          friend_request_status:
            type: string
            description: 'Status of any pending friend request between viewer and target. Empty string if no request.

              '
          is_blocked:
            type: boolean
          is_own_profile:
            type: boolean
    UpdateProfileRequest:
      type: object
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 20
          pattern: ^[a-zA-Z0-9\-]+$
          description: 3–20 characters, letters, numbers and hyphens only
        email:
          type: string
          format: email
        is_profile_public:
          type: boolean
        show_online_status:
          type: boolean
        allow_friend_requests:
          type: boolean
        allow_party_invites:
          type: boolean
        country:
          type: string
          nullable: true
        language:
          type: string
          enum:
          - en
          - fr
          - es
        bio:
          type: string
          maxLength: 50
          nullable: true
    CreateGameRequest:
      type: object
      required:
      - mode
      properties:
        mode:
          type: string
          enum:
          - solo
          - 1v1
          - multi
        question_count:
          type: integer
        points_per_correct:
          type: integer
        time_bonus:
          type: boolean
        dataset_id:
          type: string
          format: uuid
    JoinGameRequest:
      type: object
      required:
      - game_id
      properties:
        game_id:
          type: string
          format: uuid
    SubmitAnswerRequest:
      type: object
      required:
      - question_id
      - time_spent
      properties:
        question_id:
          type: string
          format: uuid
        answer_slug:
          type: string
        data:
          type: object
        time_spent:
          type: integer
    Game:
      type: object
      properties:
        id:
          type: string
          format: uuid
        public_id:
          type: string
        mode:
          type: string
        status:
          type: string
        creator_public_id:
          type: string
        question_count:
          type: integer
        dataset_id:
          type: string
          format: uuid
        winner_id:
          type: string
          format: uuid
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        players:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/GamePlayer'
    GamePlayer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        game_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        score:
          type: integer
        is_ready:
          type: boolean
        status:
          type: string
        joined_at:
          type: string
          format: date-time
        user:
          $ref: '#/components/schemas/User'
    GameAnswer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        game_id:
          type: string
          format: uuid
        player_id:
          type: string
          format: uuid
        question_id:
          type: string
          format: uuid
        answer_slug:
          type: string
        data:
          type: object
          description: Detailed answer data (coordinates, etc.)
        is_correct:
          type: boolean
        time_spent:
          type: integer
        points:
          type: integer
        answered_at:
          type: string
          format: date-time
    GameStatusResponse:
      type: object
      properties:
        game:
          $ref: '#/components/schemas/Game'
        players:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/GamePlayer'
        current_question:
          $ref: '#/components/schemas/Question'
        question_number:
          type: integer
        total_questions:
          type: integer
        time_remaining:
          type: integer
    GameHistoryResponse:
      type: object
      properties:
        game:
          $ref: '#/components/schemas/Game'
        players:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/GamePlayer'
        user_score:
          type: integer
        opponent_score:
          type: integer
        is_winner:
          type: boolean
    UserGameHistory:
      type: object
      properties:
        games:
          type: array
          items:
            $ref: '#/components/schemas/Game'
        total:
          type: integer
    Question:
      type: object
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
        version:
          type: string
        slug:
          type: string
        qtype:
          type: string
        difficulty:
          type: string
        estimated_seconds:
          type: integer
        points:
          type: number
        shuffle_answers:
          type: boolean
        dataset_id:
          type: string
          format: uuid
        theme:
          $ref: '#/components/schemas/Theme'
        subthemes:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Theme'
        tags:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Theme'
        i18n:
          type: object
        answers:
          type: array
          maxItems: 10
          items:
            type: object
        created_at:
          type: string
          format: date-time
    Theme:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
    QuestionCreateRequest:
      type: object
      required:
      - kind
      - version
      - slug
      - theme
      - qtype
      - difficulty
      - estimated_seconds
      - points
      - i18n
      - answers
      properties:
        kind:
          type: string
        version:
          type: string
        slug:
          type: string
        theme:
          $ref: '#/components/schemas/Theme'
        subthemes:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Theme'
        tags:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/Theme'
        qtype:
          type: string
        difficulty:
          type: string
        estimated_seconds:
          type: integer
        points:
          type: number
        shuffle_answers:
          type: boolean
        i18n:
          type: object
        answers:
          type: array
          maxItems: 10
          items:
            type: object
        sources:
          type: array
          maxItems: 5
          items:
            type: string
    FriendRequestResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        from_user_public_id:
          type: string
          example: '#20483-18393'
        to_user_public_id:
          type: string
          example: '#84729-93012'
        status:
          type: string
          enum:
          - pending
          - accepted
          - rejected
          - blocked
          - cancelled
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    FriendUserResponse:
      type: object
      description: Friend user info returned in friend lists and friend request details
      properties:
        public_id:
          type: string
        username:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum:
          - user
          - moderator
          - administrator
        account_status:
          type: string
        has_avatar:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        bio:
          type: string
          nullable: true
        language:
          type: string
        experience:
          type: integer
          format: int64
        level:
          type: integer
        rank:
          type: string
        elo_rating:
          type: integer
        elo_games_played:
          type: integer
        status:
          type: string
          enum:
          - online
          - offline
        is_online:
          type: boolean
        is_profile_public:
          type: boolean
        show_online_status:
          type: boolean
        allow_friend_requests:
          type: boolean
        allow_party_invites:
          type: boolean
    FriendRequestWithUser:
      type: object
      description: Friend request enriched with from/to user details (client-facing)
      properties:
        id:
          type: string
          format: uuid
        from_user:
          $ref: '#/components/schemas/FriendUserResponse'
        to_user:
          $ref: '#/components/schemas/FriendUserResponse'
        status:
          type: string
          enum:
          - pending
          - accepted
          - rejected
          - blocked
          - cancelled
        created_at:
          type: string
          format: date-time
    AdminFriendRequest:
      type: object
      description: Friend request DTO returned by admin endpoints
      properties:
        id:
          type: string
          format: uuid
        from_user_id:
          type: string
          format: uuid
        to_user_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          - accepted
          - rejected
          - blocked
          - cancelled
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AdminFriendship:
      type: object
      description: Friendship DTO returned by admin endpoints. `id` is a synthetic key `"user1_uuid:user2_uuid"`.
      properties:
        id:
          type: string
          description: Synthetic composite key "user1_uuid:user2_uuid"
        user1_id:
          type: string
          format: uuid
        user2_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
    Friend:
      type: object
      properties:
        user_id_1:
          type: string
          format: uuid
        user_id_2:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
    QuestionDataset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        version:
          type: string
        manifest_url:
          type: string
        source:
          type: string
        question_count:
          type: integer
        theme_count:
          type: integer
        is_active:
          type: boolean
        is_default:
          type: boolean
        created_at:
          type: string
          format: date-time
    CreateDatasetRequest:
      type: object
      required:
      - slug
      - name
      - version
      - source
      properties:
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        version:
          type: string
        source:
          type: string
          enum:
          - cultpedia
          - custom
          - imported
        is_default:
          type: boolean
    ImportDatasetRequest:
      type: object
      required:
      - manifest_url
      properties:
        manifest_url:
          type: string
        set_as_default:
          type: boolean
        force:
          type: boolean
    AdminCreateUser:
      type: object
      required:
      - email
      - username
      - role
      - account_status
      - password
      properties:
        email:
          type: string
          format: email
        username:
          type: string
          minLength: 3
          maxLength: 20
        password:
          type: string
          minLength: 8
        role:
          type: string
          enum:
          - user
          - moderator
          - administrator
        account_status:
          type: string
          enum:
          - active
          - suspended
          - banned
          - inactive
    AdminUpdateStatus:
      type: object
      required:
      - account_status
      properties:
        account_status:
          type: string
          enum:
          - active
          - suspended
          - banned
          - inactive
    AdminUpdatePassword:
      type: object
      required:
      - password
      properties:
        password:
          type: string
    AdminBanUser:
      type: object
      required:
      - duration
      properties:
        duration:
          type: string
          description: Ban duration (e.g. '1h', '24h', '7d', 'permanent')
          example: 24h
        reason:
          type: string
          description: Optional reason for the ban
    MaintenanceStatus:
      type: object
      properties:
        enabled:
          type: boolean
    RateLimitConfig:
      type: object
      properties:
        max_requests:
          type: integer
        window_seconds:
          type: integer
    Pagination:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        has_more:
          type: boolean
    WebSocketConfig:
      type: object
      properties:
        write_wait_seconds:
          type: integer
          description: Time allowed to write a message to the peer (default 10)
          example: 10
        pong_wait_seconds:
          type: integer
          description: Time allowed to read the next pong message (default 60)
          example: 60
        max_message_size_kb:
          type: integer
          description: Maximum message size allowed in KB (default 512)
          example: 512
    AvatarConfig:
      type: object
      properties:
        max_file_size_mb:
          type: integer
          description: Maximum avatar file size in MB (default 5)
          example: 5
        allowed_mime_types:
          type: array
          items:
            type: string
          example:
          - image/jpeg
          - image/png
        allowed_extensions:
          type: array
          items:
            type: string
          example:
          - .png
          - .jpeg
          - .jpg
    RankDefinition:
      type: object
      properties:
        name:
          type: string
          example: Intermediate
        min_level:
          type: integer
          example: 5
    XPConfig:
      type: object
      properties:
        base_xp:
          type: number
          description: Base XP for level formula (default 2000)
          example: 2000
        growth_rate:
          type: number
          description: Growth rate for level formula (default 1.5)
          example: 1.5
        solo_multiplier:
          type: number
          example: 0.5
        onevone_multiplier:
          type: number
          example: 1.0
        multi_multiplier:
          type: number
          example: 1.0
        winner_bonus:
          type: integer
          description: Flat XP bonus for the winner in 1v1 mode
          example: 100
        ranks:
          type: array
          items:
            $ref: '#/components/schemas/RankDefinition'
    ELOConfig:
      type: object
      properties:
        k_factor_low_games:
          type: integer
          description: K-factor for new players (< threshold games, default 32)
          example: 32
        k_factor_high_games:
          type: integer
          description: K-factor for experienced players (>= threshold games, default 16)
          example: 16
        k_factor_threshold:
          type: integer
          description: Games-played threshold to switch K-factor (default 30)
          example: 30
        min_rating:
          type: integer
          description: Minimum ELO rating floor (default 0)
          example: 0
        max_rating:
          type: integer
          description: Maximum ELO rating ceiling (default 9999)
          example: 9999
    GameConfig:
      type: object
      properties:
        active_ttl_minutes:
          type: integer
          description: TTL for active games in Redis in minutes (default 1440 = 24h)
          example: 1440
        finished_ttl_minutes:
          type: integer
          description: TTL for finished games in Redis in minutes (default 120 = 2h)
          example: 120
    SystemConfig:
      type: object
      description: Runtime-configurable system parameters (cache, cleanup, WebSocket delays, analytics retention, cron jobs).
      properties:
        user_cache_ttl_minutes:
          type: integer
          description: User data cache TTL in minutes (default 1440 = 24h)
          example: 1440
        cleanup_interval_minutes:
          type: integer
          description: Background cleanup interval in minutes (default 5)
          example: 5
        offline_delay_seconds:
          type: integer
          description: Seconds before marking a user offline after WebSocket disconnect (default 2)
          example: 2
        game_leave_delay_seconds:
          type: integer
          description: Seconds before removing a player from a game after disconnect (default 30)
          example: 30
        analytics_active_days:
          type: integer
          description: Days before moving analytics to archive (default 1)
          example: 1
        analytics_archive_days:
          type: integer
          description: Days to retain archived analytics (default 30)
          example: 30
        dataset_check_enabled:
          type: boolean
          description: Whether automatic dataset update checks are enabled
          example: true
        dataset_check_cron:
          type: string
          description: Cron expression for dataset update check scheduler
          example: 0 * * * *
        version_check_enabled:
          type: boolean
          description: Whether automatic server version checks are enabled
          example: true
        session_cleanup_enabled:
          type: boolean
          description: Whether automatic session cleanup is enabled
          example: true
        session_cleanup_cron:
          type: string
          description: Cron expression for session cleanup scheduler
          example: 0 * * * *
        game_cleanup_enabled:
          type: boolean
          description: Whether automatic abandoned-game cleanup is enabled
          example: true
        game_cleanup_cron:
          type: string
          description: Cron expression for game cleanup scheduler
          example: '*/5 * * * *'
    GameTemplate:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 100
          example: Classic 1v1
        description:
          type: string
          maxLength: 500
          example: Standard 1v1 mode with 10 questions
        slug:
          type: string
          example: classic-1v1
        mode:
          type: string
          enum:
          - solo
          - 1v1
          - multi
          - ''
          description: Game engine lock — empty means any mode
          example: 1v1
        min_players:
          type: integer
          minimum: 1
          example: 2
        max_players:
          type: integer
          minimum: 1
          example: 2
        question_count:
          type: integer
          minimum: 1
          example: 10
        question_type:
          type: string
          enum:
          - mcq
          - mcq_2
          - mcq_4
          - true_false
          - single_choice_2
          - mcq_2_mix
          - text_input
          - map
          - ''
          description: Filter to a specific question type; empty means all types
        dataset_id:
          type: string
          format: uuid
          nullable: true
        category:
          type: string
        flag_variant:
          type: string
        continent:
          type: string
        include_territories:
          type: boolean
          example: false
        language:
          type: string
          example: en
        points_per_correct:
          type: integer
          example: 100
        time_bonus:
          type: boolean
          example: true
        score_mode:
          type: string
          enum:
          - classic
          - time_bonus
          - fastest_wins
          example: time_bonus
        xp_multiplier:
          type: number
          nullable: true
          description: Override for global per-mode XP multiplier; null means use global setting
          example: 1.0
        is_active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    QuestionAnalytics:
      type: object
      properties:
        question_id:
          type: string
          format: uuid
        total_answers:
          type: integer
        correct_count:
          type: integer
        incorrect_count:
          type: integer
        success_rate:
          type: number
          format: float
          description: Percentage (0-100)
        avg_time_ms:
          type: number
          format: float
        answer_distribution:
          type: array
          items:
            $ref: '#/components/schemas/AnswerDistribution'
        time_distribution:
          type: array
          items:
            $ref: '#/components/schemas/TimeBucket'
    AnswerDistribution:
      type: object
      properties:
        answer_slug:
          type: string
        count:
          type: integer
        is_correct:
          type: boolean
    TimeBucket:
      type: object
      properties:
        bucket:
          type: string
          example: 1-3s
        count:
          type: integer
    QuestionDifficulty:
      type: object
      properties:
        question_id:
          type: string
          format: uuid
        total_answers:
          type: integer
        correct_count:
          type: integer
        success_rate:
          type: number
          format: float
        avg_time_ms:
          type: number
          format: float
    QuestionPlayCount:
      type: object
      properties:
        question_id:
          type: string
          format: uuid
        total_answers:
          type: integer
        success_rate:
          type: number
          format: float
    GlobalAnalytics:
      type: object
      properties:
        total_answers:
          type: integer
        avg_success_rate:
          type: number
          format: float
        avg_time_ms:
          type: number
          format: float
        answers_per_day:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              count:
                type: integer
    Report:
      type: object
      properties:
        id:
          type: string
          format: uuid
        question_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        reason:
          type: string
        message:
          type: string
        status:
          type: string
          enum:
          - pending
          - reviewed
          - resolved
          - dismissed
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        question:
          $ref: '#/components/schemas/Question'
        reporter:
          $ref: '#/components/schemas/User'
    UpdateReportStatus:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - pending
          - reviewed
          - resolved
          - dismissed
    Country:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        iso_alpha2:
          type: string
        iso_alpha3:
          type: string
        name:
          type: object
        capital:
          type: object
        continent:
          type: string
        region:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        flag:
          type: string
        population:
          type: integer
        area_km2:
          type: number
        currency:
          type: object
        languages:
          type: object
        neighbors:
          type: object
        tld:
          type: string
        phone_code:
          type: string
        driving_side:
          type: string
        un_member:
          type: boolean
    Continent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: object
        countries:
          type: object
        area_km2:
          type: integer
        population:
          type: integer
    Region:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: object
        continent:
          type: string
        countries:
          type: object
    CreateReportRequest:
      type: object
      required:
      - question_id
      - reason
      properties:
        question_id:
          type: string
          format: uuid
        reason:
          type: string
          enum:
          - wrong_answer
          - typo
          - offensive
          - other
        message:
          type: string
    ChangePasswordRequest:
      type: object
      required:
      - current_password
      - new_password
      properties:
        current_password:
          type: string
          description: The user's current password
          example: OldP@ssw0rd!
        new_password:
          type: string
          minLength: 8
          description: 'New password. Must be at least 8 characters with one uppercase letter, one digit, and one special
            character.

            '
          example: NewP@ssw0rd!
    DeleteAccountRequest:
      type: object
      required:
      - password
      properties:
        password:
          type: string
          description: Current password to confirm account deletion
          example: MyP@ssw0rd!
    UserStats:
      type: object
      properties:
        total_games:
          type: integer
        games_won:
          type: integer
        games_lost:
          type: integer
        win_rate:
          type: number
          format: double
          example: 0.65
        win_streak:
          type: integer
        best_win_streak:
          type: integer
        total_score:
          type: integer
          format: int64
        average_score:
          type: number
          format: double
        play_time:
          type: integer
          format: int64
          description: Total play time in seconds
        elo_rating:
          type: integer
          example: 1000
        elo_games_played:
          type: integer
        experience:
          type: integer
          format: int64
        level:
          type: string
        games_by_mode:
          type: array
          items:
            $ref: '#/components/schemas/GameModeStats'
        recent_games:
          type: array
          items:
            $ref: '#/components/schemas/RecentGameInfo'
    GameModeStats:
      type: object
      properties:
        mode:
          type: string
          enum:
          - solo
          - 1v1
        total_games:
          type: integer
    RecentGameInfo:
      type: object
      properties:
        game_id:
          type: string
          format: uuid
        public_id:
          type: string
        mode:
          type: string
          enum:
          - solo
          - 1v1
        status:
          type: string
          enum:
          - completed
          - cancelled
          - abandoned
        score:
          type: integer
        is_winner:
          type: boolean
        completed_at:
          type: string
          format: date-time
          nullable: true
    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - game_invite
          - friend_request
          - game_completed
          - friend_accepted
          description: Notification type
        title:
          type: string
          example: New Friend Request
        message:
          type: string
          example: player123 sent you a friend request
        data:
          type: object
          additionalProperties: true
          nullable: true
          description: Additional context data (e.g., request_id, from_user_id)
        is_read:
          type: boolean
        created_at:
          type: string
          format: date-time
    NotificationListResponse:
      type: object
      properties:
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/Notification'
        unread_count:
          type: integer
          description: Total number of unread notifications
    LeaderboardEntry:
      type: object
      properties:
        rank:
          type: integer
          example: 1
        user_id:
          type: string
          format: uuid
        username:
          type: string
          example: player123
        public_id:
          type: string
          example: ABC123XY
        has_avatar:
          type: boolean
        score:
          type: integer
          format: int64
          example: 15000
        elo_rating:
          type: integer
          example: 1250
    LeaderboardResponse:
      type: object
      properties:
        data:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/LeaderboardEntry'
        pagination:
          $ref: '#/components/schemas/Pagination'
        type:
          type: string
          enum:
          - global
          - weekly
          - monthly
          - elo
        mode:
          type: string
          enum:
          - all
          - solo
          - 1v1
        user_rank:
          allOf:
          - $ref: '#/components/schemas/LeaderboardEntry'
          nullable: true
          description: Current authenticated user's rank and score
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              additionalProperties: true
              nullable: true
    GeographyDataset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        version:
          type: string
        source:
          type: string
        manifest_url:
          type: string
        country_count:
          type: integer
        continent_count:
          type: integer
        region_count:
          type: integer
        flag_count:
          type: integer
        is_active:
          type: boolean
        is_default:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        imported_at:
          type: string
          format: date-time
    UnifiedDataset:
      type: object
      description: 'Unified dataset view returned by `GET /admin/datasets` and related endpoints. Covers both `questions`
        and `geography` dataset types in a single schema.

        '
      properties:
        id:
          type: string
          format: uuid
          example: 5d6143df-5a63-4c83-b206-a6369fbcf49d
        type:
          type: string
          enum:
          - questions
          - geography
          description: Dataset type
          example: questions
        slug:
          type: string
          example: general-knowledge-v1.0.11
        name:
          type: string
          example: general-knowledge v1.0.11
        description:
          type: string
          example: Imported from manifest on 2026-04-11
        version:
          type: string
          example: 1.0.11
        source:
          type: string
          enum:
          - manifest
          - custom
          - imported
          example: manifest
        manifest_url:
          type: string
          format: uri
          example: https://raw.githubusercontent.com/Culturae-org/cultpedia/refs/heads/main/datasets/general-knowledge/manifest.json
        is_active:
          type: boolean
          example: true
        is_default:
          type: boolean
          example: false
        imported_at:
          type: string
          format: date-time
          example: '2026-04-11T11:32:19.309225+02:00'
        update_available:
          type: boolean
          example: false
        latest_available_version:
          type: string
          nullable: true
          description: Set when `update_available` is true
          example: 1.1.0
        stats:
          type: object
          nullable: true
          description: Optional stats object (present when fetching a single dataset with stats endpoint)
          additionalProperties: true
    ImportJob:
      type: object
      description: Import job record returned by `GET /admin/imports` — reflects the real response from the live API.
      properties:
        id:
          type: string
          format: uuid
          example: 30d7e316-3e4c-41f3-906b-42329a891ac6
        manifest_url:
          type: string
          format: uri
          example: https://raw.githubusercontent.com/Culturae-org/cultpedia/refs/heads/main/datasets/general-knowledge/manifest.json
        dataset:
          type: string
          description: Dataset name / slug
          example: general-knowledge
        version:
          type: string
          example: 1.0.11
        started_at:
          type: string
          format: date-time
          example: '2026-04-11T11:32:19.309225+02:00'
        finished_at:
          type: string
          format: date-time
          example: '2026-04-11T11:32:20.277478+02:00'
        success:
          type: boolean
          example: true
        added:
          type: integer
          description: Number of records added
          example: 14
        updated:
          type: integer
          description: Number of records updated
          example: 0
        skipped:
          type: integer
          description: Number of records skipped
          example: 0
        errors:
          type: integer
          description: Number of errors encountered
          example: 0
        message:
          type: string
          example: Successfully imported 14 questions from general-knowledge
    ImportQuestionLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        import_job_id:
          type: string
          format: uuid
        question_slug:
          type: string
        action:
          type: string
        status:
          type: string
        error_message:
          type: string
        created_at:
          type: string
          format: date-time
    ImportResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        questions_added:
          type: integer
        questions_updated:
          type: integer
        questions_skipped:
          type: integer
        themes_added:
          type: integer
        subthemes_added:
          type: integer
        tags_added:
          type: integer
        errors:
          type: array
          items:
            type: string
    GeographyImportResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        countries_added:
          type: integer
        countries_updated:
          type: integer
        countries_skipped:
          type: integer
        continents_added:
          type: integer
        continents_updated:
          type: integer
        regions_added:
          type: integer
        regions_updated:
          type: integer
        errors:
          type: array
          items:
            type: string
    DatasetUpdateInfo:
      type: object
      properties:
        has_update:
          type: boolean
        current_version:
          type: string
        latest_version:
          type: string
        updated_at:
          type: string
          format: date-time
        manifest:
          type: object
    SystemMetrics:
      type: object
      properties:
        total_users:
          type: integer
        active_users:
          type: integer
        total_sessions:
          type: integer
        active_sessions:
          type: integer
        total_api_requests:
          type: integer
        error_rate:
          type: number
          format: float
        avg_response_time_ms:
          type: number
          format: float
    ServiceStatus:
      type: object
      properties:
        service_name:
          type: string
        status:
          type: string
        last_check:
          type: string
          format: date-time
        response_time_ms:
          type: number
        error_msg:
          type: string
        details:
          type: object
    APIRequestStats:
      type: object
      properties:
        total_requests:
          type: integer
        error_rate:
          type: number
          format: float
        requests_by_status:
          type: object
          additionalProperties:
            type: integer
        requests_by_method:
          type: object
          additionalProperties:
            type: integer
        requests_by_path:
          type: object
          additionalProperties:
            type: integer
        avg_response_time_ms:
          type: number
          format: float
        daily_average:
          type: number
          format: float
    AdminActionStats:
      type: object
      properties:
        total_actions:
          type: integer
        success_rate:
          type: number
          format: float
        actions_by_type:
          type: object
          additionalProperties:
            type: integer
        actions_by_resource:
          type: object
          additionalProperties:
            type: integer
        actions_by_admin:
          type: object
          additionalProperties:
            type: integer
        daily_average:
          type: number
          format: float
    UserActionStats:
      type: object
      properties:
        total_actions:
          type: integer
        success_rate:
          type: number
          format: float
        actions_by_type:
          type: object
          additionalProperties:
            type: integer
        actions_by_user:
          type: object
          additionalProperties:
            type: integer
        daily_average:
          type: number
          format: float
    FriendshipStats:
      type: object
      properties:
        total_friendships:
          type: integer
          format: int64
        total_friend_requests:
          type: integer
          format: int64
        friend_requests_by_status:
          type: object
          additionalProperties:
            type: integer
            format: int64
        friendships_by_user:
          type: object
          additionalProperties:
            type: integer
            format: int64
    GameInvite:
      type: object
      properties:
        id:
          type: string
          format: uuid
        game_id:
          type: string
          format: uuid
        from_user_id:
          type: string
          format: uuid
        to_user_id:
          type: string
          format: uuid
        status:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    GameQuestion:
      type: object
      properties:
        id:
          type: string
          format: uuid
        game_id:
          type: string
          format: uuid
        question_id:
          type: string
          format: uuid
        order:
          type: integer
        created_at:
          type: string
          format: date-time
    UserConnectionLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        ip_address:
          type: string
        user_agent:
          type: string
        device_info:
          type: string
        location:
          type: string
        is_success:
          type: boolean
        failure_reason:
          type: string
        created_at:
          type: string
          format: date-time
    Session:
      type: object
      description: 'Active session info returned by `GET /auth/sessions`. Internal token identifiers (`token_id`, `refresh_token`,
        `previous_refresh`) are intentionally omitted from this response.

        '
      properties:
        id:
          type: string
          format: uuid
          description: Session UUID (use this to revoke the session)
        created:
          type: string
          format: date-time
          description: When this session was created
        expires_at:
          type: string
          format: date-time
          description: When the refresh token expires
        last_used:
          type: string
          format: date-time
          description: Last activity timestamp for this session
        ip_address:
          type: string
          example: 203.0.113.42
        user_agent:
          type: string
          example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...
        device_fingerprint:
          type: string
          description: Hashed combination of user-agent and IP (informational)
        is_active:
          type: boolean
        is_revoked:
          type: boolean
        revoked_at:
          type: string
          format: date-time
          nullable: true
        revoked_reason:
          type: string
          nullable: true
        variables:
          type: object
          additionalProperties: true
          nullable: true
          description: 'Session metadata set at creation (e.g. `login_method`, `first_login`).

            '
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DailyGameStat:
      type: object
      properties:
        date:
          type: string
          format: date
        total_games:
          type: integer
        completed_games:
          type: integer
        cancelled_games:
          type: integer
        total_players:
          type: integer
    CreateGameReportRequest:
      type: object
      required:
      - reason
      properties:
        reason:
          type: string
          enum:
          - wrong_answer
          - typo
          - offensive
          - other
        message:
          type: string
          maxLength: 500
          description: Optional detailed explanation
    UpdateDatasetRequest:
      type: object
      description: Partial update for a dataset. All fields are optional.
      properties:
        name:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        is_active:
          type: boolean
          nullable: true
        is_default:
          type: boolean
          nullable: true
    GameStatus:
      type: object
      description: Current status snapshot of a game, returned by GET /games/{gameID}/status.
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - waiting
          - starting
          - in_progress
          - completed
          - cancelled
          example: in_progress
        mode:
          type: string
          enum:
          - solo
          - 1v1
          - multi
          example: 1v1
        current_question:
          type: integer
          description: Index of the current question (1-indexed)
          example: 3
        total_questions:
          type: integer
          example: 10
        players:
          type: array
          items:
            type: object
            properties:
              public_id:
                type: string
                example: 40093-6544
              username:
                type: string
                example: culturae-admin
              score:
                type: integer
                example: 210
              is_connected:
                type: boolean
                example: true
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
    GameHistoryItem:
      type: object
      description: A game record returned by GET /games/history.
      properties:
        id:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        public_id:
          type: string
          example: gm-abc123
        mode:
          type: string
          enum:
          - solo
          - 1v1
          - multi
          example: 1v1
        status:
          type: string
          enum:
          - completed
          - cancelled
          example: completed
        score:
          type: integer
          description: Score achieved by the authenticated player
          example: 750
        rank:
          type: integer
          description: Final rank within the game (1 = winner)
          example: 1
        question_count:
          type: integer
          example: 10
        correct_count:
          type: integer
          example: 8
        template_name:
          type: string
          nullable: true
          example: 1v1 — Capital → Country ×2
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
        xp_earned:
          type: integer
          example: 120
        elo_change:
          type: integer
          description: ELO points gained or lost (null for non-ranked modes)
          nullable: true
          example: 15
paths:
  /health:
    get:
      operationId: healthCheck
      summary: Health check
      tags:
      - System
      security: []
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
              example:
                status: healthy
  /api/v1/auth/register:
    post:
      operationId: registerUser
      summary: Register a new user
      description: 'Creates a new user account, opens a session and returns tokens.


        **Username rules:** 3–20 characters, letters/numbers/hyphens only (`^[a-zA-Z0-9\-]+$`).


        **Password rules:** Minimum 8 characters, at least one uppercase letter,

        one digit, and one special character.


        **Rate limit:** 3 attempts per hour per IP (disabled in development mode).


        **Cookies set on success:**

        - `culturae_token` — access token (HttpOnly, Secure, SameSite=Strict)

        - `culturae_refresh` — refresh token (HttpOnly, Secure, SameSite=Strict)


        A WebSocket notification (`user_registered`) is broadcast to all connected

        admins after successful registration.

        '
      tags:
      - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            example:
              email: newuser@example.com
              username: player123
              password: SecurePass1!
      responses:
        '201':
          description: User registered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              example:
                message: User created successfully
                data:
                  created: '2025-12-15T12:00:00Z'
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  refresh_token: a3f8e2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1
                  expires_at: 1734307200
                  token_expires_at: 1734219600
                  user:
                    public_id: '#20483-18393'
                    username: player123
                    email: newuser@example.com
                    language: en
                    role: user
        '400':
          description: Validation error (missing fields, invalid format, password too weak)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                username_too_short:
                  summary: Username too short
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Username must be at least 3 characters long.
                username_too_long:
                  summary: Username too long
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Username must not exceed 20 characters.
                invalid_username:
                  summary: Invalid username format
                  value:
                    error:
                      code: INVALID_FORMAT
                      message: Username can only contain letters, numbers, and hyphens.
                invalid_email:
                  summary: Invalid email format
                  value:
                    error:
                      code: INVALID_FORMAT
                      message: Invalid email format.
                weak_password:
                  summary: Password not strong enough
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Password must be at least 8 characters long and contain at least one uppercase letter, one
                        digit, and one special character.
        '409':
          description: Email or username already taken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CONFLICT
                  message: User already exists
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Session service unavailable (session or JWT service not initialised)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/auth/login:
    post:
      operationId: loginUser
      summary: Login
      description: 'Authenticates a user with email/username and password. Opens a new session

        and returns a short-lived access token + a long-lived refresh token.


        The `identifier` field accepts either an email address or a username.


        **Rate limit:** 10 attempts per 15 minutes per IP (disabled in development mode).


        **Cookies set on success:**

        - `culturae_token` — access token (HttpOnly, Secure, SameSite=Strict)

        - `culturae_refresh` — refresh token (HttpOnly, Secure, SameSite=Strict)


        For cross-platform clients (mobile, desktop) that cannot use cookies, store

        the `token` and `refresh_token` values from the response body and send

        `Authorization: Bearer <token>` on subsequent requests.

        '
      tags:
      - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            example:
              identifier: user@example.com
              password: SecurePass1!
      responses:
        '200':
          description: Login successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              example:
                message: Login successful
                data:
                  created: '2025-12-15T12:00:00Z'
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  refresh_token: a3f8e2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1
                  expires_at: 1734307200
                  token_expires_at: 1734219600
                  user:
                    public_id: '#20483-18393'
                    username: player123
                    email: user@example.com
                    language: fr
                    role: user
        '401':
          description: Invalid credentials (wrong email/username or password)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: AUTH_INVALID_CREDENTIALS
                  message: Invalid credentials
        '403':
          description: Account is banned, suspended, inactive, or deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                banned_permanent:
                  summary: Permanently banned
                  value:
                    error:
                      code: ACCOUNT_BANNED
                      message: Your account has been banned
                      details:
                        ban_reason: Cheating
                        banned_until: null
                banned_timed:
                  summary: Temporarily banned
                  value:
                    error:
                      code: ACCOUNT_BANNED
                      message: Your account has been banned
                      details:
                        ban_reason: Toxic behaviour
                        banned_until: '2026-01-15T00:00:00Z'
                suspended:
                  summary: Account suspended
                  value:
                    error:
                      code: FORBIDDEN
                      message: Account status prevents login
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Session service unavailable (session or JWT service not initialised)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/auth/refresh:
    post:
      operationId: refreshToken
      summary: Refresh access token
      description: 'Issues a new access token (and rotates the refresh token) using a valid

        refresh token.


        **Token rotation:** Every successful call generates a **new** refresh token.

        The old refresh token is immediately invalidated. Always store and use the

        latest `refresh_token` value from the response.


        **Reuse detection:** If an already-rotated (old) refresh token is submitted,

        the server treats it as a potential session hijack — **all sessions for the

        affected user are immediately revoked** and a `401` is returned. The user

        must log in again.


        **Maximum concurrent sessions:** 3 (production) / 5 (default). Oldest sessions

        are evicted when the limit is exceeded.


        The refresh token can be provided either in the request body or via the

        `culturae_refresh` HttpOnly cookie (cookie takes priority when both are absent

        from the body). The request body is optional when the cookie is present.


        **Cookies updated on success:**

        - `culturae_token` — new access token

        - `culturae_refresh` — new refresh token

        '
      tags:
      - Auth
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
            example:
              refresh_token: a3f8e2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1
      responses:
        '200':
          description: Token refreshed successfully. New access and refresh tokens issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              example:
                message: Token refreshed successfully
                data:
                  created: '2025-12-15T12:00:00Z'
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  refresh_token: b4g9f3c2d5e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
                  expires_at: 1734307200
                  token_expires_at: 1734219600
                  user:
                    public_id: '#20483-18393'
                    username: player123
                    email: user@example.com
                    language: fr
                    role: user
        '400':
          description: No refresh token provided (neither in body nor cookie)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: refresh_token is required in body or cookie
        '401':
          description: Invalid, expired, revoked, or reused refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid:
                  summary: Invalid token (not found)
                  value:
                    error:
                      code: AUTH_INVALID_TOKEN
                      message: Invalid refresh token
                expired:
                  summary: Token has expired
                  value:
                    error:
                      code: AUTH_REFRESH_EXPIRED
                      message: Refresh token expired
                revoked:
                  summary: Token was explicitly revoked
                  value:
                    error:
                      code: AUTH_SESSION_REVOKED
                      message: Refresh token revoked
                reused:
                  summary: Reuse detected — all sessions revoked
                  value:
                    error:
                      code: AUTH_INVALID_TOKEN
                      message: Invalid refresh token
        '403':
          description: Account is banned, suspended, inactive, or deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                banned:
                  summary: Account banned
                  value:
                    error:
                      code: ACCOUNT_BANNED
                      message: Your account has been banned
                      details:
                        ban_reason: Cheating
                        banned_until: null
                deleted:
                  summary: Account deleted
                  value:
                    error:
                      code: ACCOUNT_DELETED
                      message: This account has been deleted
        '503':
          description: Session service unavailable (session or JWT service not initialised)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/auth/login-admin:
    post:
      operationId: loginAdmin
      summary: Admin login
      description: 'Authenticates an administrator. Only accounts with the `administrator` role

        are accepted — any other role receives a `403 FORBIDDEN`.


        This endpoint is public (no JWT required) and is only documented in the admin

        API spec. It is the entry point for the admin dashboard and admin CLI clients.


        The `identifier` field accepts either an email address or a username.


        **Cookies set on success:**

        - `culturae_token` — access token (HttpOnly, Secure, SameSite=Strict)

        - `culturae_refresh` — refresh token (HttpOnly, Secure, SameSite=Strict)


        For non-browser admin clients, store the `token` and `refresh_token` values

        from the response body and send `Authorization: Bearer <token>` on subsequent

        requests.


        **Rate limit:** 10 attempts per 15 minutes per IP (disabled in development mode).


        **Session limits and token rotation** are identical to the regular login

        endpoint — see `POST /api/v1/auth/refresh` for details.

        '
      tags:
      - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            example:
              identifier: admin@example.com
              password: AdminPass1!
      responses:
        '200':
          description: Admin login successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              example:
                message: Login successful
                data:
                  created: '2025-12-15T12:00:00Z'
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  refresh_token: a3f8e2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1
                  expires_at: 1734307200
                  token_expires_at: 1734219600
                  user:
                    public_id: '#00001-00001'
                    username: admin
                    email: admin@example.com
                    language: en
                    role: administrator
        '401':
          description: Invalid credentials (wrong email/username or password)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: AUTH_INVALID_CREDENTIALS
                  message: Invalid credentials
        '403':
          description: Account is not an administrator, or is banned/suspended/inactive/deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_admin:
                  summary: Not an administrator
                  value:
                    error:
                      code: FORBIDDEN
                      message: 'Access denied: administrator only'
                banned:
                  summary: Account banned
                  value:
                    error:
                      code: ACCOUNT_BANNED
                      message: Your account has been banned
                      details:
                        ban_reason: Policy violation
                        banned_until: '2026-03-01T00:00:00Z'
                suspended:
                  summary: Account suspended or inactive
                  value:
                    error:
                      code: FORBIDDEN
                      message: Account status prevents login
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/auth/logout:
    post:
      operationId: logoutUser
      summary: Logout current session
      description: 'Revokes the current session identified by the JWT''s token ID.

        Clears the `culturae_token` and `culturae_refresh` cookies.


        The access token itself is short-lived and will expire naturally, but

        the session is marked as revoked immediately so subsequent requests with

        the same token are rejected by the middleware.

        '
      tags:
      - Auth
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Logged out successfully. Cookies cleared.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Logged out successfully
                  data:
                    nullable: true
              example:
                message: Logged out successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/me:
    get:
      operationId: getMe
      summary: Get basic current user info
      description: 'Returns minimal info about the authenticated user: public ID, username,

        avatar flag, language, role, and level. Used by clients to populate the navbar

        and lightweight UI components without fetching the full profile.


        Also returns `current_game_public_id` when the user is currently in an active

        game — mobile clients should check this field on startup and auto-redirect the

        player back into their in-progress game (handles accidental disconnects /

        app crashes gracefully).

        '
      tags:
      - Profile
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Basic user info
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserBasicInfo'
              example:
                data:
                  public_id: '#20483-18393'
                  username: player123
                  has_avatar: true
                  language: en
                  role: user
                  level: 5
                  rank: silver
                  elo_rating: 1234
                  current_game_public_id: gm-a1b2c3d4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/profile:
    get:
      operationId: getProfile
      summary: Get current user profile
      tags:
      - Profile
      security:
      - BearerAuth: []
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  public_id: '#20483-18393'
                  username: player123
                  email: player@example.com
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: true
                  country: FR
                  language: en
                  bio: Love geography games!
                  level: 42
                  rank: Expert
                  xp: 12500
                  elo: 1500
                  games_played: 156
                  games_won: 89
                  accuracy: 78.5
                  avg_response_time: 4.2
                  created_at: '2024-01-15T10:30:00Z'
                  updated_at: '2025-04-02T14:22:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updateProfile
      summary: Update profile
      description: 'Updates the current user''s profile. All fields are optional — only provided

        fields are updated.


        Constraints:

        - `username`: 3–20 chars, letters/numbers/hyphens only (`^[a-zA-Z0-9\-]+$`)

        - `bio`: max 50 characters

        - `language`: ISO language code (e.g. `en`, `fr`, `es`)

        '
      tags:
      - Profile
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
            example:
              username: mynewname
              bio: Passionate about culture!
              language: fr
              is_profile_public: true
              show_online_status: true
              allow_friend_requests: true
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Profile updated successfully
                  data:
                    $ref: '#/components/schemas/User'
              example:
                message: Profile updated successfully
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  public_id: '#20483-18393'
                  username: player456
                  email: newemail@example.com
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: false
                  country: FR
                  language: fr
                  bio: New bio here
                  level: 42
                  rank: Expert
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Username or email already taken
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteAccount
      summary: Delete account (soft delete)
      description: 'Permanently deactivates the account. The user data is anonymized but game history is preserved.

        All active sessions are revoked. This action cannot be undone.

        '
      tags:
      - Profile
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAccountRequest'
            example:
              password: MyP@ssw0rd!
      responses:
        '200':
          description: Account deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Account deleted successfully
                  data:
                    nullable: true
        '400':
          description: Invalid request or wrong password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                password_mismatch:
                  summary: Wrong password
                  value:
                    error:
                      code: PASSWORD_MISMATCH
                      message: password is incorrect
                validation_error:
                  summary: Validation error
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: 'Key: ''DeleteAccountRequest.Password'' Error:Field validation for ''Password'' failed on the
                        ''required'' tag'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/profile/regenerate-id:
    post:
      operationId: regeneratePublicId
      summary: Regenerate public ID
      description: 'Generates a new short public identifier for the current user.


        **Cooldown:** once per 24 hours. Returns 429 if attempted within that window.

        '
      tags:
      - Profile
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Public ID regenerated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Public ID regenerated successfully
                  data:
                    type: object
                    properties:
                      public_id:
                        type: string
                        example: '#20483-18393'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Cannot regenerate public ID while in an active game
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Cannot regenerate public ID while in an active game
        '429':
          description: Regeneration cooldown — only once per 24 hours
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: You can only regenerate your Public ID once per day
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/profile/change-password:
    post:
      operationId: changePassword
      summary: Change password
      description: 'Changes the current user''s password.


        The new password must satisfy all complexity requirements: minimum 8 characters,

        at least one uppercase letter, one digit, and one special character.


        If the server is configured with `RevokeOnPasswordChange`, all other active

        sessions are automatically revoked after a successful password change.

        '
      tags:
      - Profile
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
            example:
              current_password: OldPassword123!
              new_password: NewSecure456@
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Password changed successfully
                  data:
                    nullable: true
        '400':
          description: Invalid current password or weak new password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                wrong_password:
                  summary: Current password is incorrect
                  value:
                    error:
                      code: PASSWORD_MISMATCH
                      message: current password is incorrect
                weak_password:
                  summary: New password does not meet complexity requirements
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: password must contain at least one uppercase letter, one digit, and one special character
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/profile/stats:
    get:
      operationId: getProfileStats
      summary: Get personal game statistics
      description: |
        Returns detailed game statistics for the current user including win rate, ELO, games by mode, and recent games.
        Use `?period=week` or `?period=month` to filter stats to a recent time window. Without `period`, lifetime stats are returned.
        ELO, XP, level, and rank are always lifetime values regardless of the period filter.
      tags:
      - Profile
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: period
        schema:
          type: string
          enum:
          - week
          - month
        description: Optional time window to filter game stats. Omit for lifetime stats.
      responses:
        '200':
          description: User statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserStats'
              example:
                data:
                  total_games: 42
                  games_won: 28
                  games_lost: 14
                  win_rate: 0.667
                  win_streak: 3
                  best_win_streak: 7
                  total_score: 12500
                  average_score: 297.6
                  play_time: 7200
                  elo_rating: 1150
                  elo_games_played: 20
                  experience: 5000
                  level: intermediate
                  games_by_mode:
                  - mode: solo
                    total_games: 30
                  - mode: 1v1
                    total_games: 12
                  recent_games:
                  - game_id: 00000000-0000-0000-0000-000000000001
                    public_id: abc123
                    mode: 1v1
                    status: completed
                    score: 450
                    is_winner: true
                    completed_at: '2026-02-07T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/avatar:
    post:
      operationId: uploadAvatar
      summary: Upload avatar
      description: 'Uploads an avatar image for the current user. The allowed file types and

        maximum file size are governed by the server''s avatar configuration

        (see `GET /api/v1/admin/settings/avatar`). Defaults: `.jpg`, `.jpeg`, `.png`,

        max 5 MB.

        '
      tags:
      - Avatar
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - avatar
              properties:
                avatar:
                  type: string
                  format: binary
                  description: Image file (jpg/jpeg/png)
          application/json:
            example: null
      responses:
        '200':
          description: Avatar uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Avatar uploaded successfully
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      has_avatar:
                        type: boolean
                        example: true
        '400':
          description: No file uploaded, invalid file type, or file too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no_file:
                  summary: No file provided
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: No file uploaded
                invalid_type:
                  summary: Invalid file type
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid file type. Only .jpg, .jpeg, .png are allowed.
                file_too_large:
                  summary: File exceeds size limit
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: File size exceeds the configured limit.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteAvatar
      summary: Delete avatar
      tags:
      - Avatar
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Avatar deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Avatar deleted successfully
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      has_avatar:
                        type: boolean
                        example: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No avatar to delete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: No avatar to delete
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/avatar/{publicID}:
    get:
      operationId: getAvatar
      summary: Get user avatar
      description: 'Returns the avatar image for the user identified by their public ID.


        The `publicID` path parameter is the numeric portion of the public ID —

        the leading `#` is stripped. For example, for user `#20483-18393`, pass

        `20483-18393`.


        If the target user''s profile is private, the requester must be authenticated

        and a friend of the target user; otherwise 403 is returned.

        '
      tags:
      - Avatar
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: publicID
        required: true
        schema:
          type: string
        description: Public ID without the leading `#` (e.g. `20483-18393`)
      responses:
        '200':
          description: Avatar image (raw binary)
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '403':
          description: Profile is private and requester is not a friend
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Profile is private
        '404':
          description: User not found or user has no avatar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    error:
                      code: NOT_FOUND
                      message: User not found
                no_avatar:
                  summary: User has no avatar
                  value:
                    error:
                      code: NOT_FOUND
                      message: No avatar found
  /api/v1/users/search:
    get:
      operationId: searchUsers
      summary: Search / list public profiles
      description: 'Returns public profiles matching the query. If `q` is omitted or empty,

        returns all public profiles (paginated).

        '
      tags:
      - Users
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: q
        required: false
        schema:
          type: string
        description: Search query (username). If empty, returns all public profiles.
      - in: query
        name: page
        schema:
          type: integer
          default: 1
      - in: query
        name: limit
        schema:
          type: integer
          default: 20
          maximum: 50
      responses:
        '200':
          description: Profile list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      profiles:
                        type: array
                        items:
                          $ref: '#/components/schemas/PublicProfile'
                      page:
                        type: integer
                      limit:
                        type: integer
              example:
                data:
                - public_id: 40093-6544
                  username: culturae-admin
                  has_avatar: true
                  language: en
                  role: administrator
                  level: 0
                  rank: Beginner
                  elo_rating: 1000
                pagination:
                  total: 1
                  limit: 20
                  offset: 0
                  has_more: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/users/profile/{publicID}:
    get:
      operationId: getUserProfile
      summary: Get public profile with relationship
      description: 'Returns a user''s public profile enriched with relationship context

        for the authenticated viewer (is_friend, is_blocked, is_own_profile, etc.).


        Returns 404 if: user not found, profile is private, or the target has

        blocked the viewer.

        '
      tags:
      - Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: publicID
        required: true
        schema:
          type: string
        description: The full public ID of the user including `#` (e.g., `#20483-18393`)
      responses:
        '200':
          description: Public profile with relationship context
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserProfileWithRelationship'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: User not found, profile is private, or viewer is blocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Profile not found
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/friends:
    get:
      operationId: listFriends
      summary: List friends
      description: Returns all friends of the authenticated user as `FriendUserResponse` objects.
      tags:
      - Friends
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Friend list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    nullable: true
                    items:
                      $ref: '#/components/schemas/FriendUserResponse'
              example:
                data:
                - id: 660e8400-e29b-41d4-a716-446655440001
                  public_id: '#20483-18394'
                  username: geo_master
                  has_avatar: true
                  level: 56
                  rank: Master
                  is_online: true
                - id: 770e8400-e29b-41d4-a716-446655440002
                  public_id: '#20483-18395'
                  username: flag_expert
                  has_avatar: false
                  level: 34
                  rank: Intermediate
                  is_online: false
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/requests:
    get:
      operationId: listFriendRequests
      summary: List friend requests
      description: 'Returns friend requests for the authenticated user.

        Filter by `status` (default: `pending`) and direction `type` (`incoming` or `outgoing`, default: `incoming`).

        '
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: status
        schema:
          type: string
          default: pending
        description: Filter by request status (e.g. `pending`, `accepted`, `rejected`)
      - in: query
        name: type
        schema:
          type: string
          enum:
          - incoming
          - outgoing
          default: incoming
        description: Direction of requests (`incoming` = received by you, `outgoing` = sent by you)
      responses:
        '200':
          description: Friend requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FriendRequestWithUser'
              example:
                data:
                - id: 990e8400-e29b-41d4-a716-446655440099
                  status: pending
                  direction: incoming
                  created_at: '2025-04-01T10:00:00Z'
                  user:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    public_id: '#20483-18394'
                    username: geo_master
                    has_avatar: true
                    level: 56
                    rank: Master
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/request/{toUserPublicID}:
    post:
      operationId: sendFriendRequest
      summary: Send friend request
      description: 'Sends a friend request to the target user. The `{toUserPublicID}` path parameter

        is the **target user''s public ID** (e.g. `#20483-18393`).

        '
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: toUserPublicID
        required: true
        schema:
          type: string
        description: Public ID of the target user (e.g. `#20483-18393`)
      responses:
        '201':
          description: Friend request sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FriendRequestResponse'
        '400':
          description: Cannot send request (already friends, request exists, blocked, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: User not found
        200:
          description: Success
          content:
            application/json:
              example:
                data:
                  id: 00000000-0000-0000-0000-000000000000
                  from_user_public_id: 40093-6544
                  to_user_public_id: 12345-6789
                  status: pending
                   created_at: '2026-04-11T12:00:00Z'
  /api/v1/friends/request/{requestID}:
    delete:
      operationId: cancelFriendRequest
      summary: Cancel friend request
      description: 'Cancels a pending outgoing friend request. The `{requestID}` path parameter

        is the **friend request UUID** (from `GET /friends/requests`).

        '
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: requestID
        required: true
        schema:
          type: string
          format: uuid
        description: UUID of the friend request to cancel
      responses:
        '200':
          description: Request cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Friend request cancelled
                  data:
                    nullable: true
              example:
                message: Friend request cancelled
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/accept/{requestID}:
    post:
      operationId: acceptFriendRequest
      summary: Accept friend request
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: requestID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Friend request accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Friend request accepted
                  data:
                    nullable: true
              example:
                message: Friend request accepted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/reject/{requestID}:
    post:
      operationId: rejectFriendRequest
      summary: Reject friend request
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: requestID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Friend request rejected
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Friend request rejected
                  data:
                    nullable: true
              example:
                message: Friend request rejected
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/block/{requestID}:
    post:
      operationId: blockFriendRequest
      summary: Block user via friend request
      description: Block a user by the ID of their pending friend request.
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: requestID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User blocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User blocked
                  data:
                    nullable: true
              example:
                message: User blocked
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/{friendUserPublicID}:
    delete:
      operationId: removeFriend
      summary: Remove friend
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: friendUserPublicID
        required: true
        schema:
          type: string
        description: Public ID of the friend to remove (e.g. `#20483-18393`)
      responses:
        '200':
          description: Friend removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Friend removed
                  data:
                    nullable: true
              example:
                message: Friend removed
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/blocked:
    get:
      operationId: getBlockedUsers
      summary: Get blocked users
      description: Returns the list of users blocked by the authenticated user.
      tags:
      - Friends
      security:
      - BearerAuth: []
      responses:
        '200':
          description: List of blocked users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    nullable: true
                    items:
                      $ref: '#/components/schemas/PublicUser'
              example:
                data: []
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/block-user/{userPublicID}:
    post:
      operationId: blockUser
      summary: Block a user
      description: 'Blocks a user by their public ID. If a friendship or pending friend request exists,

        it will be removed. Blocked users cannot send friend requests or game invites.

        Cannot block yourself.

        '
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userPublicID
        required: true
        schema:
          type: string
        description: The public ID of the user to block
        example: '#20483-18393'
      responses:
        '200':
          description: User blocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User blocked
                  data:
                    nullable: true
        '400':
          description: Invalid request or self-action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                self_action:
                  summary: Cannot block yourself
                  value:
                    error:
                      code: SELF_ACTION
                      message: cannot block yourself
                validation:
                  summary: Invalid public ID
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid user public ID
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/friends/blocked/{userPublicID}:
    delete:
      operationId: unblockUser
      summary: Unblock a user
      description: Unblocks a previously blocked user by their public ID.
      tags:
      - Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userPublicID
        required: true
        schema:
          type: string
        description: The public ID of the user to unblock
        example: '#20483-18393'
      responses:
        '200':
          description: User unblocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User unblocked
                  data:
                    nullable: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: user is not blocked
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/game-templates:
    get:
      operationId: getGameTemplates
      summary: List active game templates
      description: Returns all active game templates available to players. Used to populate game creation UIs.
      tags:
      - Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: List of active game templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GameTemplate'
              example:
                data:
                - id: 7a2a94a1-9320-40a9-a010-552ffaa4d722
                  name: 1v1 — Capital → Country ×2
                  slug: 1v1-flags-capital-to-name-2
                  mode: 1v1
                  min_players: 2
                  max_players: 2
                  question_count: 10
                  is_active: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/admin/game-templates:
    get:
      operationId: adminListGameTemplates
      summary: List all game templates (admin)
      tags:
      - Admin Game Templates
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of all game templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GameTemplate'
              example:
                data:
                - id: 7a2a94a1-9320-40a9-a010-552ffaa4d722
                  name: Classic 1v1
                  slug: classic-1v1
                  description: Standard 1v1 mode with 10 questions
                  mode: 1v1
                  min_players: 2
                  max_players: 2
                  question_count: 10
                  is_active: true
                  created_at: '2025-01-01T00:00:00Z'
                pagination:
                  total: 5
                  limit: 50
                  offset: 0
                  has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: adminCreateGameTemplate
      summary: Create game template
      tags:
      - Admin Game Templates
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                slug:
                  type: string
                mode:
                  type: string
                min_players:
                  type: integer
                max_players:
                  type: integer
                question_count:
                  type: integer
                is_active:
                  type: boolean
      responses:
        '201':
          description: Template created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GameTemplate'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/game-templates/{id}:
    get:
      operationId: adminGetGameTemplate
      summary: Get game template
      tags:
      - Admin Game Templates
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Template details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GameTemplate'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: adminUpdateGameTemplate
      summary: Update game template
      tags:
      - Admin Game Templates
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Template updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GameTemplate'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: adminDeleteGameTemplate
      summary: Delete game template
      tags:
      - Admin Game Templates
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Template deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/game-templates/seed-defaults:
    post:
      operationId: adminSeedDefaultTemplates
      summary: Seed default templates
      tags:
      - Admin Game Templates
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Templates seeded
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  seeded: 5
                  message: 5 default templates created
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/games/create:
    post:
      operationId: createGame
      summary: Create a game
      tags:
      - Games
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGameRequest'
            example:
              mode: 1v1
              template_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
              is_ranked: true
              question_count: 10
              time_per_question: 15
      responses:
        '201':
          description: Game created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Game'
              example:
                message: Game created successfully
                data:
                  id: f47ac10b-58cc-4372-a567-0e02b2c3d479
                  public_id: GAME-ABC123
                  mode: 1v1
                  status: waiting
                  is_ranked: true
                  question_count: 10
                  time_per_question: 15
                  creator_id: 550e8400-e29b-41d4-a716-446655440000
                  players:
                  - user_id: 550e8400-e29b-41d4-a716-446655440000
                    username: player123
                    is_ready: true
                    score: 0
                  created_at: '2025-04-03T10:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/games/{gameID}/start:
    post:
      operationId: startGame
      summary: Start a game
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: gameID
        required: true
        schema:
          type: string
          format: uuid
        description: The game UUID
      responses:
        '200':
          description: Ready to start — game has been queued to start
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Ready to start
                  data:
                    nullable: true
              example:
                message: Ready to start
        '400':
          description: Cannot start game (game not ready, player not in game, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Only the creator can start
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/games/{gameID}/invite/{toUserPublicID}:
    post:
      operationId: inviteToGame
      summary: Invite user to game
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: gameID
        required: true
        schema:
          type: string
      - in: path
        name: toUserPublicID
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Invitation sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/GameInvite'
        '400':
          description: Cannot invite
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Game or user not found
        200:
          description: Success
          content:
            application/json:
              example:
                data:
                  id: 00000000-0000-0000-0000-000000000000
                  status: pending
                  created_at: '2026-04-11T12:00:00Z'
  /api/v1/games/invite/{inviteID}/accept:
    post:
      operationId: acceptGameInvite
      summary: Accept game invite
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: inviteID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Invitation accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invitation accepted
                  data:
                    type: object
                    properties:
                      game_public_id:
                        type: string
                        description: Public ID of the game to join
                        example: abc123
              example:
                message: Game invite accepted
        '400':
          description: Cannot accept (already accepted, expired, etc.)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Invitation not found
  /api/v1/games/invite/{inviteID}/reject:
    post:
      operationId: rejectGameInvite
      summary: Reject game invite
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: inviteID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Invitation rejected
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invitation rejected
                  data:
                    nullable: true
              example:
                message: Game invite rejected
        '400':
          description: Cannot reject (already rejected, expired, etc.)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Invitation not found
  /api/v1/games/invite/{inviteID}/cancel:
    post:
      operationId: cancelUserGameInvite
      summary: Cancel a sent game invite
      description: Allows the invite sender to cancel a pending invite they sent. Sends a `game_invite_cancelled` WebSocket event to the recipient and removes the associated notification.
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: inviteID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Invite cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: invite cancelled
        '400':
          description: Invite is not pending
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not the sender of the invite
        '404':
          description: Invite not found
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/games/matchmaking/join:
    post:
      operationId: joinMatchmaking
      tags:
      - Games
      summary: Join matchmaking queue
      description: Join the matchmaking queue for a specific game mode
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mode
              properties:
                mode:
                  type: string
                  enum:
                  - 1v1
                  description: Only `1v1` is currently supported
                category:
                  type: string
                  description: Question category filter
                flag_variant:
                  type: string
                  description: Flag game variant (e.g. `flags`, `map`)
                language:
                  type: string
                  description: Language for questions (e.g. `en`, `fr`)
                question_count:
                  type: integer
                  description: Number of questions for the game
            example:
              mode: 1v1
              template_id: 7a2a94a1-9320-40a9-a010-552ffaa4d722
      responses:
        '200':
          description: Successfully joined queue
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Joined matchmaking queue
                  data:
                    nullable: true
              example:
                message: Joined matchmaking queue
                data:
                  mode: 1v1
                  position: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/games/matchmaking/leave:
    post:
      operationId: leaveMatchmaking
      tags:
      - Games
      summary: Leave matchmaking queue
      description: Leave the matchmaking queue for a specific game mode
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mode
              properties:
                mode:
                  type: string
                  enum:
                  - 1v1
            example:
              mode: 1v1
      responses:
        '200':
          description: Successfully left queue
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Left matchmaking queue
                  data:
                    nullable: true
              example:
                message: Left matchmaking queue
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/games/join-by-code:
    post:
      operationId: joinGameByCode
      summary: Join a game by code
      description: |
        Join a 1v1 or multi game using its public code (the game's `public_id`).
        Validates that the game is in `waiting` status, not full, and that the caller is not already a player.
        Sends a `player_joined` WebSocket event to all players in the game room.
      tags:
      - Games
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: The game's public_id (shown to the creator as a shareable code).
                  example: a1b2c3d4
      responses:
        '200':
          description: Joined game
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: joined game
        '400':
          description: Invalid game mode, game not waiting, or other validation error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Game not found
        '409':
          description: Game is full or player already in game
  /api/v1/games/{gameID}/leave:
    post:
      operationId: leaveGame
      summary: Leave a game
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: gameID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Left game
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Left game successfully
                  data:
                    nullable: true
              example:
                message: Left game
        '400':
          description: Cannot leave
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/games/{gameID}/cancel:
    post:
      operationId: cancelGame
      summary: Cancel a game
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: gameID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Game cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Game cancelled
                  data:
                    nullable: true
              example:
                message: Game cancelled
        '400':
          description: Cannot cancel (game not in waiting/playing state, not the creator, etc.)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/games/{gameID}/answer:
    post:
      operationId: submitAnswer
      summary: Submit an answer
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: gameID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAnswerRequest'
            example:
              question_id: d311236a-441a-4379-b3ce-54cdc5364195
              answer_slug: 300000-km-s
              time_spent: 4500
      responses:
        '200':
          description: Answer submitted — result delivered via WebSocket (`answer_received` event)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Answer submitted
                  data:
                    nullable: true
              example:
                data:
                  is_correct: true
                  points: 110
                  time_bonus: 10
                  correct_answer: 300000-km-s
        '400':
          description: Invalid answer (invalid question ID, bad slug, negative time, etc.)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/games/{gameID}/status:
    get:
      operationId: getGameStatus
      summary: Get game status
      description: Returns the current status of a game including players, current question, scores, etc.
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: gameID
        required: true
        schema:
          type: string
          format: uuid
        description: The game UUID
      responses:
        '200':
          description: Game status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GameStatus'
              example:
                data:
                  game_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
                  status: in_progress
                  current_question_index: 3
                  current_question:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    question: What is the capital of France?
                    answers:
                    - id: '1'
                      label: Paris
                    - id: '2'
                      label: London
                    - id: '3'
                      label: Berlin
                    - id: '4'
                      label: Madrid
                    correct_answer_id: '1'
                    time_remaining: 12
                  players:
                  - user_id: 550e8400-e29b-41d4-a716-446655440000
                    username: player123
                    score: 80
                    correct_answers: 3
                    is_online: true
                  - user_id: 660e8400-e29b-41d4-a716-446655440001
                    username: player456
                    score: 60
                    correct_answers: 2
                    is_online: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/games/{gameID}/results:
    get:
      operationId: getGameResults
      summary: Get post-game results
      description: |
        Returns detailed results for a completed game: final scores per player, question-by-question
        breakdown, and each player's answers. Only accessible to players who participated in the game.
        The game must have `status: completed`.
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: gameID
        required: true
        schema:
          type: string
        description: The game's public_id
      responses:
        '200':
          description: Game results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      game:
                        type: object
                        properties:
                          public_id:
                            type: string
                          mode:
                            type: string
                          status:
                            type: string
                          started_at:
                            type: string
                            format: date-time
                            nullable: true
                          completed_at:
                            type: string
                            format: date-time
                            nullable: true
                          winner_public_id:
                            type: string
                            nullable: true
                      players:
                        type: array
                        items:
                          type: object
                          properties:
                            public_id:
                              type: string
                            username:
                              type: string
                            score:
                              type: integer
                            is_winner:
                              type: boolean
                      questions:
                        type: array
                        items:
                          type: object
                          properties:
                            order_number:
                              type: integer
                            question_title:
                              type: string
                            question_type:
                              type: string
                            correct_answer:
                              type: string
                            answers:
                              type: array
                              items:
                                type: object
                                properties:
                                  player_public_id:
                                    type: string
                                  answer:
                                    type: string
                                  is_correct:
                                    type: boolean
                                  points:
                                    type: integer
                                  time_spent_ms:
                                    type: integer
        '400':
          description: Game is not completed
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not a participant of this game
        '404':
          description: Game not found
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/games/active:
    get:
      operationId: getActiveGames
      summary: Get active games
      description: Returns a list of games that are currently waiting for players or in progress
      tags:
      - Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Active games
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Game'
              example:
                data:
                - id: f47ac10b-58cc-4372-a567-0e02b2c3d479
                  public_id: GAME-ABC123
                  mode: 1v1
                  status: waiting
                  is_ranked: true
                  players:
                  - user_id: 550e8400-e29b-41d4-a716-446655440000
                    username: player123
                  created_at: '2025-04-03T10:00:00Z'
                - id: g58ad21c-69dd-5483-b678-1f03c3d4e590
                  public_id: GAME-DEF456
                  mode: solo
                  status: in_progress
                  is_ranked: false
                  players:
                  - user_id: 660e8400-e29b-41d4-a716-446655440001
                    username: player456
                  created_at: '2025-04-03T09:45:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/games/history:
    get:
      operationId: getGameHistory
      summary: Get game history
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          default: 20
          maximum: 100
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Game history (paginated)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GameHistoryItem'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
                      has_more:
                        type: boolean
              example:
                data: []
                pagination:
                  total: 0
                  limit: 20
                  offset: 0
                  has_more: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/games/invites:
    get:
      operationId: getGameInvites
      summary: Get game invites
      description: 'Returns game invites for the authenticated user. Filter by status using the query parameter.

        '
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: status
        schema:
          type: string
          enum:
          - pending
          - accepted
          - rejected
          - cancelled
          - all
          default: pending
        description: Filter invites by status. Use "all" to return invites of any status.
      responses:
        '200':
          description: List of game invites
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GameInvite'
        '400':
          description: Invalid status parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: 'Invalid status. Use: pending, accepted, rejected, cancelled, all'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/notifications:
    get:
      operationId: getNotifications
      summary: List notifications
      description: Returns paginated notifications for the authenticated user. Notifications are created when a friend request is received, a friend request is accepted, or a game invite is received.
      tags:
      - Notifications
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: unread_only
        schema:
          type: boolean
          default: false
        description: If true, return only unread notifications.
      - in: query
        name: limit
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        description: Number of notifications to return.
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Pagination offset.
      responses:
        '200':
          description: List of notifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        type:
                          type: string
                          example: game_invite
                        title:
                          type: string
                        body:
                          type: string
                        data:
                          type: object
                          nullable: true
                        is_read:
                          type: boolean
                        created_at:
                          type: string
                          format: date-time
                  total:
                    type: integer
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440000
                  type: game_invite
                  title: Game invitation
                  body: alice invited you to a game
                  data:
                    invite_id: 660e8400-e29b-41d4-a716-446655440001
                  is_read: false
                  created_at: '2026-04-27T10:00:00Z'
                total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/notifications/{id}/read:
    patch:
      operationId: markNotificationAsRead
      summary: Mark a notification as read
      tags:
      - Notifications
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Notification marked as read
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: Notification marked as read
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Notification not found or does not belong to the user
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/notifications/read-all:
    post:
      operationId: markAllNotificationsAsRead
      summary: Mark all notifications as read
      tags:
      - Notifications
      security:
      - BearerAuth: []
      responses:
        '200':
          description: All notifications marked as read
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: All notifications marked as read
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/lobby/stats:
    get:
      operationId: getLobbyStats
      summary: Get lobby statistics
      description: 'Returns real-time lobby statistics: number of online users, active games

        per mode, and players waiting in the matchmaking queue per mode.


        This is a **public** endpoint (no authentication required). Useful for

        displaying lobby activity on landing pages or pre-login screens.

        '
      tags:
      - System
      security: []
      responses:
        200:
          description: Current lobby stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      online_users:
                        type: integer
                        description: Number of users currently connected via WebSocket
                        example: 142
                      active_games:
                        type: object
                        description: 'Map of game mode → number of active games.

                          Keys are game modes (e.g. `"solo"`, `"1v1"`, `"multi"`).

                          Empty object `{}` when no games are active.

                          '
                        additionalProperties:
                          type: integer
                        example:
                          solo: 12
                          1v1: 7
                      in_queue:
                        type: object
                        description: 'Map of game mode → number of players waiting in the matchmaking queue.

                          Empty object `{}` when nobody is queuing.

                          '
                        additionalProperties:
                          type: integer
                        example:
                          1v1: 3
              example:
                data:
                  online_users: 142
                  active_games:
                    solo: 12
                    1v1: 7
                  in_queue:
                    1v1: 3
  /api/v1/realtime:
    get:
      operationId: connectRealtime
      summary: Real-time WebSocket Connection
      description: "Establish a persistent WebSocket connection for real-time features.\n\n## Purpose\nThis endpoint provides\
        \ three main functionalities:\n\n### 1. Online Presence\n- Your online status is automatically tracked when connected\n\
        - Other users can see if you're online\n- Status updates when you disconnect\n\n### 2. Real-time Game Events\n- Receive\
        \ live updates during multiplayer games\n- Submit answers in real-time\n- See opponent actions instantly\n- Get notified\
        \ of game state changes\n\n### 3. Notifications\n- Game invitations from friends\n- Friend requests\n- Game results\n\
        \n## Connection\n```javascript\n// Browser (recommended): use an HttpOnly Secure cookie set by the server\n// (the\
        \ browser will send it automatically during the WebSocket handshake)\nconst ws = new WebSocket('wss://api.culturae.me/api/v1/realtime')\n\
        \n// Browser (alternative): pass the raw JWT as a Sec-WebSocket-Protocol\n// subprotocol (no prefixes). Example:\n\
        const ws = new WebSocket('wss://api.culturae.me/api/v1/realtime', ['<RAW_JWT_TOKEN>'])\n\n// Non-browser / native\
        \ clients (recommended): set the Authorization header\n// in the initial handshake:\n// Node.js example (ws library):\n\
        // const ws = new WebSocket('wss://api.culturae.me/api/v1/realtime', {\n//   headers: { Authorization: 'Bearer YOUR_JWT_TOKEN'\
        \ }\n// })\n\n// Native clients (iOS/Android/Desktop/Electron): use query param\nconst ws = new WebSocket('wss://api.culturae.me/api/v1/realtime?token=YOUR_JWT_TOKEN')\n\
        ```\n\nNotes:\n- For browser clients, prefer HttpOnly Secure cookies (most secure)\n- For native/mobile clients that\
        \ cannot set custom headers on WebSocket upgrade,\n  use the `?token=` query parameter\n- The server accepts JWTs\
        \ via:\n  - an HttpOnly Secure cookie (preferred for browsers),\n  - the Authorization header (Bearer) for non-browser\
        \ clients,\n  - Sec-WebSocket-Protocol subprotocol (browser-friendly fallback),\n  - `?token=` query parameter (for\
        \ native clients that cannot set headers on upgrade)\n\n## Client -> Server Messages\n| Type | Description | Required\
        \ Fields |\n|------|-------------|-----------------|\n| `ping` | Keep connection alive | - |\n| `join_game` | Join\
        \ a game room | `game_public_id` |\n| `leave_game` | Leave current game | - |\n| `submit_answer` | Submit answer in\
        \ game | `answer` object |\n| `player_ready` | Mark yourself ready | `ready` (boolean) |\n| `start_game` | Start game\
        \ (creator only) | `game_public_id` |\n\n## Server -> Client Messages\n| Type | Description |\n|------|-------------|\n\
        | `hello` | Sent immediately on connection. Contains protocol version and server info |\n| `pong` | Response to ping\
        \ |\n| `ack` | Action acknowledgment |\n| `game_created` | New game created |\n| `game_ready` | All players ready\
        \ |\n| `game_started` | Game has begun |\n| `game_completed` | Game finished |\n| `game_cancelled` | Game was cancelled\
        \ |\n| `player_joined` | Player joined game |\n| `player_left` | Player left game |\n| `player_ready` | Player ready\
        \ status changed |\n| `question_sent` | New question available |\n| `answer_received` | Answer was processed |\n|\
        \ `score_updated` | Score changed |\n| `game_invite` | Received game invitation |\n| `game_invite_accepted` | Invitation\
        \ was accepted |\n| `game_invite_rejected` | Invitation was rejected |\n| `error` | Error occurred |\n"
      tags:
      - Realtime
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: token
        schema:
          type: string
        description: JWT access token (for native clients that cannot set headers on WebSocket upgrade)
      responses:
        '101':
          description: Switching Protocols to WebSocket
          example: Upgrade successful. Connection established.
        '400':
          description: Invalid user ID in token
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Failed to upgrade WebSocket connection
        200:
          description: Success
          content:
            application/json:
              example: null
  /api/v1/geography/flags/{country_code}:
    get:
      operationId: getFlagImage
      summary: Get flag image for a country
      tags:
      - Geography
      security:
      - BearerAuth: []
      parameters:
      - name: country_code
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Flag image (SVG or PNG)
          content:
            image/svg+xml:
              schema:
                type: string
                format: binary
              example: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 60 36\">\n  <rect fill=\"#0055A4\" width=\"\
                60\" height=\"36\"/>\n  <rect fill=\"#FFFFFF\" x=\"20\" y=\"0\" width=\"20\" height=\"36\"/>\n  <rect fill=\"\
                #EF4135\" x=\"30\" y=\"0\" width=\"10\" height=\"36\"/>\n</svg>\n"
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/geography/flags/{country_code}/url:
    get:
      operationId: getFlagUrl
      summary: Get flag URL for a country
      tags:
      - Geography
      security:
      - BearerAuth: []
      parameters:
      - name: country_code
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Flag URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      country_code:
                        type: string
                      url:
                        type: string
              example:
                data:
                  country_code: FR
                  url: https://flagcdn.com/w320/fr.png
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/geography/countries:
    get:
      operationId: getCountries
      summary: List countries
      description: 'Returns a paginated list of countries from the default geography dataset.

        Supports filtering by continent and region.

      tags:
      - Geography
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - in: query
        name: continent
        schema:
          type: string
        description: Filter by continent slug
      - in: query
        name: region
        schema:
          type: string
        description: Filter by region name
      responses:
        '200':
          description: List of countries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
                  has_more:
                    type: boolean
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440000
                  name: France
                  slug: france
                  iso_alpha2: FR
                  iso_alpha3: FRA
                  continent: europe
                  region: western-europe
                  capital: Paris
                  population: 67390000
                  area: 643801
                pagination:
                  total: 195
                  limit: 50
                  offset: 0
                  has_more: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          description: No geography dataset available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: SERVICE_UNAVAILABLE
                  message: No geography dataset available
  /api/v1/geography/continents:
    get:
      operationId: getContinents
      summary: List continents
      description: 'Returns a list of continents from the default geography dataset.'
      tags:
      - Geography
      security:
      - BearerAuth: []
      responses:
        '200':
          description: List of continents
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440001
                  name: Europe
                  slug: europe
                  countries_count: 44
                - id: 550e8400-e29b-41d4-a716-446655440002
                  name: Asia
                  slug: asia
                  countries_count: 48
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          description: No geography dataset available
  /api/v1/leaderboard:
    get:
      operationId: getLeaderboard
      summary: Get leaderboard
      description: 'Returns player rankings. Supports multiple leaderboard types and game mode filters.

        Results are cached for 5 minutes. If authenticated, includes the current user''s rank.


        **Leaderboard types:**

        - `global` — All-time rankings by total score

        - `weekly` — Rankings by score earned in the last 7 days

        - `monthly` — Rankings by score earned in the last 30 days

        - `elo` — Rankings by ELO rating (1v1 competitive)

        '
      tags:
      - Leaderboard
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: type
        schema:
          type: string
          enum:
          - global
          - weekly
          - monthly
          - elo
          default: global
        description: Leaderboard type
      - in: query
        name: mode
        schema:
          type: string
          enum:
          - all
          - solo
          - 1v1
          default: all
        description: Game mode filter (applies to weekly/monthly types)
      - in: query
        name: limit
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        description: Number of entries to return
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Offset for pagination
      responses:
        '200':
          description: Leaderboard data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardResponse'
              example:
                data:
                  entries:
                  - rank: 1
                    user_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    username: top_player
                    public_id: '#20483-18393'
                    has_avatar: true
                    score: 25000
                    elo_rating: 1450
                  - rank: 2
                    user_id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    username: challenger
                    public_id: '#12345-67890'
                    has_avatar: false
                    score: 22000
                    elo_rating: 1380
                  user_rank:
                    rank: 42
                    user_id: c3d4e5f6-a7b8-9012-cdef-123456789012
                    username: current_user
                    public_id: '#11111-22222'
                    has_avatar: true
                    score: 8500
                    elo_rating: 1100
                  type: global
                  mode: all
                  total_users: 2
        '400':
          description: Invalid leaderboard type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: 'Invalid leaderboard type. Use: global, weekly, monthly, elo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v1/admin/info:
    get:
      operationId: adminGetPlatformInfo
      summary: Get platform info
      description: Returns service name, version, build time, and environment. Admin-only.
      tags:
      - Admin
      security:
      - BearerAuth: []
      responses:
        200:
          description: Platform info
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      service:
                        type: string
                        example: culturae-server
                      version:
                        type: string
                        example: v0.1.0
                      build_time:
                        type: string
                        description: Build timestamp ("unknown" in development mode)
                        example: unknown
                      environment:
                        type: string
                        enum:
                        - development
                        - production
                        - staging
                        example: development
              example:
                data:
                  service: culturae-server
                  version: v0.1.0
                  build_time: unknown
                  environment: development
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/me:
    get:
      operationId: adminGetCurrentUser
      summary: Get current admin user
      description: Returns the full admin profile of the currently authenticated administrator.
      tags:
      - Admin
      security:
      - BearerAuth: []
      responses:
        200:
          description: Admin user profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AdminUser'
              example:
                data:
                  id: 1d65428d-29be-4ae2-947d-ce9cf7f94db2
                  email: admin@culturae.me
                  username: culturae-admin
                  public_id: 40093-6544
                  role: administrator
                  account_status: active
                  has_avatar: true
                  created_at: '2026-04-10T23:00:46.846682+02:00'
                  updated_at: '2026-04-11T17:45:05.089901+02:00'
                  language: en
                  experience: 0
                  level: 0
                  rank: Beginner
                  elo_rating: 1000
                  elo_games_played: 0
                  status: online
                  is_online: true
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: true
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/realtime:
    get:
      operationId: adminConnectRealtime
      summary: Admin real-time WebSocket connection
      description: 'Establishes a persistent WebSocket connection for admin users. Admin clients

        receive admin-only broadcasts (`BroadcastAdminNotification`) in addition to

        all standard game events.


        Same authentication methods as the user WebSocket endpoint apply (cookie,

        Authorization header, Sec-WebSocket-Protocol subprotocol, or `?token=` query param).

        '
      tags:
      - Admin
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: token
        schema:
          type: string
        description: JWT access token (for native clients that cannot set headers on WebSocket upgrade)
      responses:
        '101':
          description: Switching Protocols to WebSocket
        '400':
          description: Invalid user ID in token
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: Failed to upgrade WebSocket connection
        200:
          description: Success
          content:
            application/json:
              example: null
  /api/v1/admin/users:
    get:
      operationId: adminListUsers
      summary: Get all users
      description: Returns a paginated list of all users with optional filters.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/role'
      - $ref: '#/components/parameters/account_status'
      - in: query
        name: rank
        schema:
          type: string
        description: Filter by rank name (e.g. `Beginner`, `Expert`)
      - in: query
        name: status
        schema:
          type: string
          enum:
          - online
          - offline
        description: Filter by online/offline status
      responses:
        '200':
          description: Paginated list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminUser'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 1d65428d-29be-4ae2-947d-ce9cf7f94db2
                  email: admin@culturae.me
                  username: culturae-admin
                  public_id: 40093-6544
                  role: administrator
                  account_status: active
                  has_avatar: true
                  created_at: '2026-04-10T23:00:46.846682+02:00'
                  updated_at: '2026-04-11T17:45:05.089901+02:00'
                  language: en
                  experience: 0
                  level: 0
                  rank: Beginner
                  elo_rating: 1000
                  elo_games_played: 0
                  status: online
                  is_online: true
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: true
                pagination:
                  total: 1
                  limit: 50
                  offset: 0
                  has_more: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: adminCreateUser
      summary: Create user
      description: Creates a new user account. Broadcasts a WebSocket admin notification on success.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateUser'
            example:
              email: newuser@example.com
              username: newplayer
              password: SecurePass1!
              role: user
              account_status: active
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AdminUser'
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  public_id: '#20483-99999'
                  username: newuser_admin
                  email: newuser@example.com
                  role: user
                  account_status: active
                  level: 1
                  rank: Beginner
                  xp: 0
                  elo: 1000
                  games_played: 0
                  games_won: 0
                  created_at: '2025-04-03T10:00:00Z'
                  updated_at: '2025-04-03T10:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Email or username already exists
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/users/count:
    get:
      operationId: adminGetUserCount
      summary: Get user count
      description: Returns a single integer — the total number of users matching the given filters.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/role'
      - $ref: '#/components/parameters/level'
      - $ref: '#/components/parameters/rank'
      - $ref: '#/components/parameters/account_status'
      responses:
        '200':
          description: User count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: integer
                    format: int64
                    example: 1
              example:
                data: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/users/count/online:
    get:
      operationId: adminGetOnlineUserCount
      summary: Get online user count
      description: Returns a single integer — the number of currently online users matching the given filters.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/role'
      - $ref: '#/components/parameters/level'
      - $ref: '#/components/parameters/rank'
      - $ref: '#/components/parameters/account_status'
      responses:
        '200':
          description: Online user count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: integer
                    format: int64
                    example: 5
              example:
                data: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/users/count/active/weekly:
    get:
      operationId: adminGetWeeklyActiveUserCount
      summary: Get weekly active user count
      description: Returns a single integer — the number of users active in the last 7 days matching optional filters.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/role'
      - $ref: '#/components/parameters/level'
      - $ref: '#/components/parameters/rank'
      - $ref: '#/components/parameters/account_status'
      responses:
        '200':
          description: Weekly active user count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: integer
                    format: int64
                    example: 120
              example:
                data: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/users/search:
    get:
      operationId: adminSearchUsers
      summary: Search users (admin)
      description: Full-text search over username and email. Returns paginated `AdminUser` list.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: query
        required: true
        schema:
          type: string
        description: Search term (username or email)
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Paginated search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminUser'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440000
                  public_id: '#20483-18393'
                  username: player123
                  email: player@example.com
                  role: user
                  account_status: active
                  level: 42
                  rank: Expert
                  xp: 12500
                  elo: 1500
                  games_played: 156
                  games_won: 89
                  is_online: true
                  created_at: '2024-01-15T10:30:00Z'
                pagination:
                  total: 25
                  limit: 20
                  offset: 0
        '400':
          description: Missing search query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/users/{id}:
    get:
      operationId: adminGetUser
      summary: Get user by ID
      description: Returns detailed information about a specific user by their UUID.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The user UUID
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AdminUser'
              example:
                data: &id002
                  id: 1d65428d-29be-4ae2-947d-ce9cf7f94db2
                  email: admin@culturae.me
                  username: culturae-admin
                  public_id: 40093-6544
                  role: administrator
                  account_status: active
                  has_avatar: true
                  created_at: '2026-04-10T23:00:46.846682+02:00'
                  updated_at: '2026-04-11T18:45:54.891003+02:00'
                  language: en
                  experience: 0
                  level: 0
                  rank: Beginner
                  elo_rating: 1000
                  elo_games_played: 0
                  status: online
                  is_online: true
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: adminUpdateUser
      summary: Update user
      description: 'Updates the specified user. All `UserUpdate` fields are optional.


        Notes:

        - `language` must be one of: `en`, `fr`, `es`

        - `bio` max 50 characters

        - `account_status` cannot be set to `deleted` — use the delete endpoint instead

        - Setting status to `inactive` or `banned` automatically revokes all user sessions

        '
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
            example:
              username: renamed-player
              role: moderator
              account_status: active
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AdminUser'
              example:
                data: *id002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: adminDeleteUser
      summary: Delete user
      description: 'Permanently deletes the user from the database. All sessions are revoked first.

        This is a hard delete (not soft delete).

        '
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User deleted successfully
                  data:
                    nullable: true
              example:
                message: User deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/{id}/password:
    put:
      operationId: adminUpdateUserPassword
      summary: Update user password
      description: Forcefully sets a new password for the specified user (no current password required).
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdatePassword'
            example:
              password: NewSecurePass1!
      responses:
        '200':
          description: Password updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Password updated successfully
                  data:
                    nullable: true
              example:
                message: Password updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/{id}/deactivate:
    patch:
      operationId: adminDeactivateUser
      summary: Deactivate user
      description: 'Sets the user''s account status to `inactive`. All active sessions are

        immediately revoked. Broadcasts a WebSocket admin notification.

        No-op if already inactive.

        '
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User deactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User deactivated successfully
                  data:
                    nullable: true
              example:
                data:
                  id: 1d65428d-29be-4ae2-947d-ce9cf7f94db2
                  email: admin@culturae.me
                  username: culturae-admin
                  public_id: 40093-6544
                  role: administrator
                  account_status: inactive
                  has_avatar: true
                  created_at: '2026-04-10T23:00:46.846682+02:00'
                  updated_at: '2026-04-11T18:45:54.891003+02:00'
                  language: en
                  experience: 0
                  level: 0
                  rank: Beginner
                  elo_rating: 1000
                  elo_games_played: 0
                  status: online
                  is_online: true
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/{id}/status:
    patch:
      operationId: adminUpdateUserStatus
      summary: Update user status
      description: 'Updates the account status of the specified user.


        When set to `inactive` or `banned`, all active sessions are automatically revoked.

        Broadcasts a WebSocket admin notification on success.

        '
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_status
              properties:
                account_status:
                  type: string
                  enum:
                  - active
                  - suspended
                  - banned
                  - inactive
            example:
              account_status: suspended
      responses:
        '200':
          description: Status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User status updated successfully
                  data:
                    $ref: '#/components/schemas/AdminUser'
              example:
                data:
                  id: 1d65428d-29be-4ae2-947d-ce9cf7f94db2
                  email: admin@culturae.me
                  username: culturae-admin
                  public_id: 40093-6544
                  role: administrator
                  account_status: suspended
                  has_avatar: true
                  created_at: '2026-04-10T23:00:46.846682+02:00'
                  updated_at: '2026-04-11T18:45:54.891003+02:00'
                  language: en
                  experience: 0
                  level: 0
                  rank: Beginner
                  elo_rating: 1000
                  elo_games_played: 0
                  status: online
                  is_online: true
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/{id}/regenerate-id:
    post:
      operationId: adminRegenerateUserId
      summary: Regenerate user Public ID (Admin)
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Public ID regenerated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Public ID regenerated successfully
                  data:
                    $ref: '#/components/schemas/AdminUser'
              example:
                data:
                  id: 1d65428d-29be-4ae2-947d-ce9cf7f94db2
                  email: admin@culturae.me
                  username: culturae-admin
                  public_id: 12345-6789
                  role: administrator
                  account_status: active
                  has_avatar: true
                  created_at: '2026-04-10T23:00:46.846682+02:00'
                  updated_at: '2026-04-11T18:45:54.891003+02:00'
                  language: en
                  experience: 0
                  level: 0
                  rank: Beginner
                  elo_rating: 1000
                  elo_games_played: 0
                  status: online
                  is_online: true
                  is_profile_public: true
                  show_online_status: true
                  allow_friend_requests: true
                  allow_party_invites: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/level-stats:
    get:
      operationId: adminGetLevelStats
      summary: Get user level statistics
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Level stats (map of rank name to count)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      type: integer
                    example:
                      Beginner: 10
                      Intermediate: 5
                      Expert: 2
              example:
                data:
                  Beginner: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/users/role-stats:
    get:
      operationId: adminGetRoleStats
      summary: Get user role statistics
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Role stats (map of role name to count)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      type: integer
                    example:
                      user: 100
                      moderator: 5
                      administrator: 2
              example:
                data:
                  administrator: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/users/creation-dates:
    get:
      operationId: adminGetCreationDates
      summary: Get user creation dates
      description: Returns a list of user account creation dates (format `YYYY-MM-DD`) in the given range.
      tags:
      - Admin Users
      security:
      - BearerAuth: []
      parameters:
      - name: start_date
        in: query
        description: Start date filter (format `2006-01-02`)
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End date filter (format `2006-01-02`)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: List of creation dates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                      format: date
                    example:
                    - '2025-01-15'
                    - '2025-01-16'
                    - '2025-02-03'
              example:
                data:
                - '2026-04-10T00:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/avatar/{userID}:
    post:
      operationId: adminUploadAvatar
      summary: Upload avatar for a user
      description: 'Uploads or replaces the avatar image for the specified user.

        Respects the same file type and size limits as the user-facing upload

        (governed by avatar config — see `GET /api/v1/admin/settings/avatar`).

        '
      tags:
      - Admin Avatar
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userID
        required: true
        schema:
          type: string
          format: uuid
        description: The UUID of the target user
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - avatar
              properties:
                avatar:
                  type: string
                  format: binary
                  description: Image file (jpg/jpeg/png)
          application/json:
            example: null
      responses:
        '200':
          description: Avatar uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Avatar uploaded successfully
                  data:
                    type: object
                    properties:
                      has_avatar:
                        type: boolean
                        example: true
        '400':
          description: No file, invalid type, or file too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no_file:
                  summary: No file provided
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: No file uploaded
                invalid_type:
                  summary: Invalid file type
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid file type. Only .jpg, .jpeg, .png are allowed.
                file_too_large:
                  summary: File exceeds size limit
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: File size exceeds the configured limit.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: adminDeleteAvatar
      summary: Delete avatar for a user
      tags:
      - Admin Avatar
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userID
        required: true
        schema:
          type: string
          format: uuid
        description: The UUID of the target user
      responses:
        '200':
          description: Avatar deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Avatar deleted successfully
                  data:
                    type: object
                    properties:
                      has_avatar:
                        type: boolean
                        example: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User has no avatar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: No avatar to delete
    get:
      operationId: adminGetAvatar
      summary: Get avatar for a user
      description: Returns the raw avatar image bytes for the specified user.
      tags:
      - Admin Avatar
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userID
        required: true
        schema:
          type: string
          format: uuid
        description: The UUID of the target user
      responses:
        '200':
          description: Avatar image (raw binary)
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: User not found or user has no avatar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    error:
                      code: NOT_FOUND
                      message: User not found
                no_avatar:
                  summary: User has no avatar
                  value:
                    error:
                      code: NOT_FOUND
                      message: User has no avatar
  /api/v1/admin/logs/connections/{id}:
    get:
      operationId: adminGetUserConnectionLogs
      summary: Get user connection logs
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/success'
      responses:
        '200':
          description: Connection logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserConnectionLog'
              example:
                data: []
                pagination:
                  total: 0
                  limit: 50
                  offset: 0
                  has_more: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/logs/user-actions/{id}:
    get:
      operationId: adminGetUserActionLogs
      summary: Get user action logs
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        200:
          description: Paginated action logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 660e8400-e29b-41d4-a716-446655440001
                  user_id: 550e8400-e29b-41d4-a716-446655440000
                  username: player123
                  action: game_join
                  category: game
                  ip_address: 192.168.1.100
                  user_agent: Mozilla/5.0...
                  timestamp: '2025-04-03T10:30:00Z'
                pagination:
                  total: 150
                  limit: 20
                  offset: 0
  /api/v1/admin/logs/active-sessions/{id}:
    get:
      operationId: adminGetUserActiveSessions
      summary: Get user active sessions
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Active sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Session'
              example:
                data:
                - session_id: sess_abc123def456
                  user_id: 550e8400-e29b-41d4-a716-446655440000
                  device_type: web
                  browser: Chrome
                  os: Windows
                  ip_address: 192.168.1.100
                  created_at: '2025-04-03T09:00:00Z'
                  expires_at: '2025-04-10T09:00:00Z'
                  last_activity: '2025-04-03T14:30:00Z'
                  is_current: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/logs/user-actions:
    get:
      operationId: adminListUserActionLogs
      summary: Get all user action logs
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/date_from'
      - $ref: '#/components/parameters/date_to'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/action'
      - name: user_id
        in: query
        description: Filter logs by user UUID
        schema:
          type: string
          format: uuid
      responses:
        200:
          description: Paginated user action logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 660e8400-e29b-41d4-a716-446655440002
                  user_id: 550e8400-e29b-41d4-a716-446655440000
                  username: player123
                  action: game_answer
                  category: game
                  ip_address: 192.168.1.100
                  user_agent: Mozilla/5.0...
                  timestamp: '2025-04-03T12:45:00Z'
                  details:
                    game_id: 770e8400-e29b-41d4-a716-446655440000
                    question_id: 880e8400-e29b-41d4-a716-446655440000
                    correct: true
                pagination:
                  total: 3500
                  limit: 20
                  offset: 0
  /api/v1/admin/logs/admin-actions:
    get:
      operationId: adminListAdminActionLogs
      summary: Get admin action logs
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/date_from'
      - $ref: '#/components/parameters/date_to'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - $ref: '#/components/parameters/action'
      - $ref: '#/components/parameters/admin_id'
      - name: resource
        in: query
        description: Resource type to filter (e.g., users, games)
        schema:
          type: string
      - name: resource_id
        in: query
        description: Resource UUID to filter
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/is_success'
      responses:
        200:
          description: Paginated admin action logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 880e8400-e29b-41d4-a716-446655440001
                  admin_id: 550e8400-e29b-41d4-a716-446655440000
                  admin_username: admin01
                  action: user_update
                  resource: user
                  resource_id: 660e8400-e29b-41d4-a716-446655440000
                  is_success: true
                  ip_address: 192.168.1.50
                  user_agent: Mozilla/5.0...
                  timestamp: '2025-04-03T15:00:00Z'
                  details:
                    changes:
                      username:
                        from: oldname
                        to: newname
                pagination:
                  total: 850
                  limit: 20
                  offset: 0
  /api/v1/admin/logs/connections:
    get:
      operationId: adminListConnectionLogs
      summary: Get all connection logs
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/date_from'
      - $ref: '#/components/parameters/date_to'
      - $ref: '#/components/parameters/start_date'
      - $ref: '#/components/parameters/end_date'
      - name: user_id
        in: query
        description: Filter by user UUID
        schema:
          type: string
          format: uuid
      responses:
        200:
          description: Paginated connection logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserConnectionLog'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 990e8400-e29b-41d4-a716-446655440001
                  user_id: 550e8400-e29b-41d4-a716-446655440000
                  username: player123
                  action: login
                  success: true
                  ip_address: 192.168.1.100
                  user_agent: Mozilla/5.0...
                  timestamp: '2025-04-03T10:00:00Z'
                pagination:
                  total: 2800
                  limit: 20
                  offset: 0
  /api/v1/admin/logs/system-metrics:
    get:
      operationId: adminGetSystemMetrics
      summary: Get system metrics
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      responses:
        200:
          description: System metrics
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  cpu_usage: 45.2
                  memory_usage: 68.5
                  disk_usage: 32.1
                  active_connections: 1250
                  requests_per_second: 342.5
                  uptime_seconds: 864000
                  timestamp: '2025-04-03T10:00:00Z'
  /api/v1/admin/logs/service-status:
    get:
      operationId: adminGetServiceStatus
      summary: Get service status
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      responses:
        200:
          description: Service status
          content:
            application/json:
              schema:
                type: object
              example:
                services:
                - name: api
                  status: healthy
                  uptime: 864000
                  last_check: '2025-04-03T10:00:00Z'
                - name: database
                  status: healthy
                  uptime: 864000
                  last_check: '2025-04-03T10:00:00Z'
                - name: cache
                  status: healthy
                  uptime: 864000
                  last_check: '2025-04-03T10:00:00Z'
                - name: websocket
                  status: healthy
                  uptime: 864000
                  last_check: '2025-04-03T10:00:00Z'
  /api/v1/admin/logs/api-requests/stats:
    get:
      operationId: adminGetApiRequestStats
      summary: Get API request stats
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      responses:
        200:
          description: API request statistics
          content:
            application/json:
              schema:
                type: object
              example:
                stats:
                  total_requests: 1250000
                  successful_requests: 1245000
                  failed_requests: 5000
                  avg_response_time_ms: 45.2
                  p95_response_time_ms: 120.5
                  p99_response_time_ms: 250.0
  /api/v1/admin/logs/api-requests/timestamps:
    get:
      operationId: adminGetApiRequestTimestamps
      summary: Get API request timestamps
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/date_from'
      - $ref: '#/components/parameters/date_to'
      responses:
        200:
          description: Request timestamps
          content:
            application/json:
              schema:
                type: object
              example:
                timestamps:
                - '2025-04-03T10:00:00Z'
                - '2025-04-03T10:00:01Z'
                - '2025-04-03T10:00:02Z'
                - '2025-04-03T10:00:03Z'
                - '2025-04-03T10:00:04Z'
  /api/v1/admin/logs/admin-actions/stats:
    get:
      operationId: adminGetAdminActionStats
      summary: Get admin action stats
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      responses:
        200:
          description: Admin action statistics
          content:
            application/json:
              schema:
                type: object
              example:
                stats:
                  total_actions: 1523
                  user_bans: 45
                  user_unbans: 12
                  question_deletes: 23
                  question_updates: 156
                  dataset_imports: 8
                  settings_changes: 34
  /api/v1/admin/logs/user-actions/stats:
    get:
      operationId: adminGetUserActionStats
      summary: Get user action stats
      tags:
      - Admin Logs
      security:
      - BearerAuth: []
      responses:
        200:
          description: User action statistics
          content:
            application/json:
              schema:
                type: object
              example:
                stats:
                  total_actions: 45678
                  game_joins: 12340
                  game_creates: 5678
                  friend_requests_sent: 8901
                  friend_requests_accepted: 7654
                  questions_answered: 34567
                  reports_submitted: 234
  /api/v1/admin/questions:
    get:
      operationId: adminListQuestions
      summary: List questions
      tags:
      - Admin Questions
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/dataset_id'
      - name: theme
        in: query
        description: Filter by theme
        schema:
          type: string
      - name: subtheme
        in: query
        description: Filter by subtheme
        schema:
          type: string
      - name: difficulty
        in: query
        description: Filter by difficulty
        schema:
          type: string
      - name: qtype
        in: query
        description: Filter by question type
        schema:
          type: string
      - name: tags
        in: query
        description: Comma-separated list of tags
        schema:
          type: string
      - $ref: '#/components/parameters/search'
      responses:
        200:
          description: Paginated list of questions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Question'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440000
                  slug: capital-of-france
                  question: What is the capital of France?
                  answer: Paris
                  theme: Geography
                  subtheme: European Capitals
                  difficulty: easy
                  qtype: text
                  dataset_id: 660e8400-e29b-41d4-a716-446655440000
                  tags:
                  - europe
                  - capitals
                  - france
                  correct_count: 450
                  incorrect_count: 23
                  created_at: '2024-01-15T10:30:00Z'
                pagination:
                  total: 1500
                  limit: 20
                  offset: 0
    post:
      operationId: adminCreateQuestion
      summary: Create question
      tags:
      - Admin Questions
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionCreateRequest'
            example:
              kind: question
              version: '1.0'
              slug: my-question-slug
              theme:
                slug: science
              qtype: single_choice
              difficulty: easy
              estimated_seconds: 15
              shuffle_answers: true
              i18n:
                en:
                  stem: What is 2+2?
                  title: Basic Math
                  explanation: Two plus two equals four.
              answers:
              - slug: four
                is_correct: true
                i18n:
                  en:
                    label: '4'
              - slug: three
                is_correct: false
                i18n:
                  en:
                    label: '3'
              sources: []
      responses:
        201:
          description: Question created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Question'
              example:
                data:
                  id: 770e8400-e29b-41d4-a716-446655440000
                  slug: new-question-created
                  question: What is the largest ocean?
                  answer: Pacific Ocean
                  theme: Geography
                  subtheme: Oceans
                  difficulty: easy
                  qtype: text
                  dataset_id: 660e8400-e29b-41d4-a716-446655440000
                  tags:
                  - oceans
                  - geography
                  created_at: '2025-04-03T10:00:00Z'
  /api/v1/admin/questions/{id}:
    get:
      operationId: adminGetQuestion
      summary: Get question
      tags:
      - Admin Questions
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        200:
          description: Question details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Question'
              example:
                data:
                  id: d311236a-441a-4379-b3ce-54cdc5364195
                  kind: question
                  version: '1.0'
                  slug: science-physics-light-speed-vacuum
                  qtype: single_choice
                  difficulty: intermediate
                  estimated_seconds: 20
                  shuffle_answers: true
                  dataset_id: 5d6143df-5a63-4c83-b206-a6369fbcf49d
                  theme:
                    id: 004194cc-74f5-434d-843f-a341fac6efdd
                    slug: science
                  i18n:
                    en:
                      stem: What is the speed of light in a vacuum?
                      title: Speed of Light
                      explanation: The speed of light in a vacuum is approximately 299,792 km/s.
                  answers:
                  - slug: 300000-km-s
                    is_correct: true
                    i18n:
                      en:
                        label: 300,000 km/s
                  - slug: 150000-km-s
                    is_correct: false
                    i18n:
                      en:
                        label: 150,000 km/s
                  sources:
                  - https://en.wikipedia.org/wiki/Speed_of_light
                  times_played: 0
                  times_correct: 0
                  success_rate: 0
avg_time_ms: 0
                  answers_per_day: null
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/questions/slug/{slug}:
    get:
      operationId: adminGetQuestionBySlug
      summary: Get question by slug
      tags:
      - Admin Questions
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: slug
        required: true
        schema:
          type: string
        description: Question slug
      responses:
        '200':
          description: Question details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Question'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/questions/{id}:
    put:
      operationId: adminUpdateQuestion
      summary: Update question
      tags:
      - Admin Questions
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionCreateRequest'
      responses:
        '200':
          description: Question updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Question'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: adminDeleteQuestion
      summary: Delete question
      tags:
      - Admin Questions
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Question deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/questions/export:
    get:
      operationId: adminExportQuestions
      summary: Export questions
      description: Export all questions (filtered by dataset_id if provided)
      tags:
      - Admin Questions
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: dataset_id
        schema:
          type: string
          format: uuid
        description: Filter by dataset ID
      - in: query
        name: include_hash
        schema:
          type: boolean
        description: Include answer hashes for migration
      responses:
        '200':
          description: Exported questions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
              example:
                data:
                - id: d311236a-441a-4379-b3ce-54cdc5364195
                  kind: question
                  version: '1.0'
                  slug: science-physics-light-speed-vacuum
                  qtype: single_choice
                  difficulty: intermediate
                  estimated_seconds: 20
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/friends/requests/{userID}:
    get:
      operationId: adminListFriendRequestsForUser
      summary: Get friend requests for a user
      tags:
      - Admin Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userID
        required: true
        schema:
          type: string
          format: uuid
        description: User UUID
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Friend requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminFriendRequest'
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440001
                  from_user_id: 550e8400-e29b-41d4-a716-446655440010
                  to_user_id: 550e8400-e29b-41d4-a716-446655440020
                  status: pending
                  created_at: '2025-04-15T10:00:00Z'
                pagination:
                  total: 1
                  limit: 50
                  offset: 0
                  has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/friends/{userID}:
    get:
      operationId: adminListFriendsForUser
      summary: Get friends for a user
      tags:
      - Admin Friends
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userID
        required: true
        schema:
          type: string
          format: uuid
        description: User UUID
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Friends list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminFriendship'
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440010:550e8400-e29b-41d4-a716-446655440020
                  user1_id: 550e8400-e29b-41d4-a716-446655440010
                  user2_id: 550e8400-e29b-41d4-a716-446655440020
                  created_at: '2025-04-10T10:00:00Z'
                pagination:
                  total: 1
                  limit: 50
                  offset: 0
                  has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/imports:
    get:
      operationId: adminListImportJobs
      summary: List import jobs
      tags:
      - Admin Imports
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - in: query
        name: type
        schema:
          type: string
          enum:
          - questions
          - geography
        description: Filter by import type
      responses:
        '200':
          description: Import jobs list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440001
                  manifest_url: https://example.com/manifest.json
                  dataset: general-knowledge
                  version: 1.0.0
                  started_at: '2025-04-11T11:32:00Z'
                  success: true
                  added: 14
                  updated: 0
                  skipped: 0
                  errors: 0
                  message: Successfully imported
                pagination:
                  total: 1
                  limit: 20
                  offset: 0
                  has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/imports/stats:
    get:
      operationId: adminGetImportStats
      summary: Get import statistics
      tags:
      - Admin Imports
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Import statistics
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  total_imports: 5
                  successful_imports: 4
                  failed_imports: 1
                  total_questions_added: 150
                  total_questions_updated: 25
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/imports/{id}:
    get:
      operationId: adminGetImportJob
      summary: Get import job details
      tags:
      - Admin Imports
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: Job UUID
      responses:
        '200':
          description: Import job details
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440001
                  manifest_url: https://example.com/manifest.json
                  dataset: general-knowledge
                  version: 1.0.0
                  started_at: '2025-04-11T11:32:00Z'
                  finished_at: '2025-04-11T11:35:00Z'
                  success: true
                  added: 14
                  updated: 0
                  skipped: 0
                  errors: 0
                  message: Successfully imported
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/imports/{id}/logs:
    get:
      operationId: adminGetImportJobLogs
      summary: Get import job logs
      tags:
      - Admin Imports
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: Job UUID
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - in: query
        name: action
        schema:
          type: string
        description: Filter by action (added, updated, skipped, error)
      responses:
        '200':
          description: Import job logs
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440001
                  job_id: 550e8400-e29b-41d4-a716-446655440001
                  line: 1
                  slug: science-physics-light-speed-vacuum
                  action: added
                - id: 550e8400-e29b-41d4-a716-446655440002
                  job_id: 550e8400-e29b-41d4-a716-446655440001
                  line: 2
                  slug: science-math-pythagoras
                  action: skipped
                  message: Duplicate question
                pagination:
                  total: 2
                  limit: 50
                  offset: 0
                  has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/settings/auth:
    get:
      operationId: adminGetAuthConfig
      summary: Get authentication configuration
      description: 'Returns the runtime-configurable authentication settings (token TTLs,

        session limits, login lockout parameters).

        '
      tags:
      - Admin Settings
      security:
      - BearerAuth: []
      responses:
        200:
          description: Current auth config
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      access_token_ttl_minutes:
                        type: integer
                        description: Access token lifetime in minutes (default 15)
                        example: 15
                      refresh_token_ttl_days:
                        type: integer
                        description: Refresh token lifetime in days (default 7)
                        example: 7
                      session_ttl_days:
                        type: integer
                        description: Session lifetime in days (default 30)
                        example: 30
                      max_concurrent_sessions:
                        type: integer
                        description: Maximum allowed concurrent sessions per user (default 5)
                        example: 5
                      failed_login_attempts:
                        type: integer
                        description: Failed attempts before temporary lockout (default 5)
                        example: 5
                      login_lockout_minutes:
                        type: integer
                        description: Lockout duration in minutes after too many failed attempts (default 15)
                        example: 15
              example:
                data:
                  access_token_ttl_minutes: 15
                  refresh_token_ttl_days: 7
                  session_ttl_days: 30
                  max_concurrent_sessions: 5
                  failed_login_attempts: 5
                  login_lockout_minutes: 15
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: adminUpdateAuthConfig
      summary: Update authentication configuration
      description: 'Persists new authentication parameters in Redis. Changes apply to new

        sessions only — existing sessions are not affected.

        '
      tags:
      - Admin Settings
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token_ttl_minutes:
                  type: integer
                  minimum: 1
                  example: 15
                refresh_token_ttl_days:
                  type: integer
                  minimum: 1
                  example: 7
                session_ttl_days:
                  type: integer
                  minimum: 1
                  example: 30
                max_concurrent_sessions:
                  type: integer
                  minimum: 1
                  example: 5
                failed_login_attempts:
                  type: integer
                  minimum: 1
                  example: 5
                login_lockout_minutes:
                  type: integer
                  minimum: 0
                  example: 15
            example:
              access_token_ttl_minutes: 30
              refresh_token_ttl_days: 14
              session_ttl_days: 60
              max_concurrent_sessions: 3
              failed_login_attempts: 5
              login_lockout_minutes: 30
      responses:
        200:
          description: Auth config updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      access_token_ttl_minutes:
                        type: integer
                      refresh_token_ttl_days:
                        type: integer
                      session_ttl_days:
                        type: integer
                      max_concurrent_sessions:
                        type: integer
                      failed_login_attempts:
                        type: integer
                      login_lockout_minutes:
                        type: integer
              example:
                data:
                  access_token_ttl_minutes: 30
                  refresh_token_ttl_days: 14
                  session_ttl_days: 60
                  max_concurrent_sessions: 3
                  failed_login_attempts: 5
                  login_lockout_minutes: 30
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/settings/version-status:
    get:
      operationId: adminGetVersionStatus
      summary: Get version status
      description: 'Returns the current server version and compares it with the latest available version from the remote manifest.'
      tags:
      - Admin Settings
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Version status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      current_version:
                        type: string
                      latest_version:
                        type: string
                      update_available:
                        type: boolean
                      check_performed_at:
                        type: string
                        format: date-time
              example:
                data:
                  current_version: 1.0.0
                  latest_version: 1.0.1
                  update_available: true
                  check_performed_at: '2026-04-19T10:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/datasets/{id}:
    get:
      operationId: adminGetDataset
      summary: Get a dataset by ID
      description: Returns a single dataset (questions or geography) by its UUID.
      tags:
      - Admin Datasets
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Dataset UUID
      responses:
        200:
          description: Dataset
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UnifiedDataset'
              example:
                data: *id005
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: adminUpdateDataset
      summary: Update a dataset
      description: Partial update of a dataset (name, description, is_active, is_default).
      tags:
      - Admin Datasets
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatasetRequest'
            example:
              name: Renamed Dataset
              is_active: true
              is_default: false
      responses:
        200:
          description: Dataset updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UnifiedDataset'
              example:
                data: *id005
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: adminDeleteDataset
      summary: Delete a dataset
      description: 'Permanently deletes a dataset. Use `force: true` in body to bypass active check.'
      tags:
      - Admin Datasets
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                force:
                  type: boolean
                  description: Force deletion even if dataset is active
                  example: false
            example:
              force: false
      responses:
        200:
          description: Dataset deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Dataset deleted successfully
              example:
                message: Dataset deleted successfully
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/datasets/slug/{slug}:
    get:
      operationId: adminGetDatasetBySlug
      summary: Get a dataset by slug
      description: Returns a single dataset (questions or geography) by its slug.
      tags:
      - Admin Datasets
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: Dataset slug
        example: general-knowledge-v1.0.11
      responses:
        200:
          description: Dataset
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UnifiedDataset'
              example:
                data: *id005
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/datasets/history:
    get:
      operationId: adminGetDatasetsHistory
      summary: Get dataset import history
      description: Returns the import history for all datasets.
      tags:
      - Admin Datasets
      security:
      - BearerAuth: []
      responses:
        200:
          description: Dataset history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ImportJob'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 30d7e316-3e4c-41f3-906b-42329a891ac6
                  manifest_url: https://raw.githubusercontent.com/Culturae-org/cultpedia/refs/heads/main/datasets/general-knowledge/manifest.json
                  dataset: general-knowledge
                  version: 1.0.11
                  started_at: '2026-04-11T11:32:19.309225+02:00'
                  finished_at: '2026-04-11T11:32:20.277478+02:00'
                  success: true
                  added: 14
                  updated: 0
                  skipped: 0
                  errors: 0
                  message: Successfully imported 14 questions from general-knowledge
                pagination:
                  total: 2
                  limit: 20
                  offset: 0
has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}/events:
    get:
      operationId: adminGetGameEventLogs
      summary: Get game event logs
      description: Returns the event log for a game (state transitions, player actions, WebSocket events).
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Game UUID
      responses:
        '200':
          description: Game event logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/GlobalAnalytics'
              example:
                data:
                  total_answers: 0
                  avg_success_rate: 0
                  avg_time_ms: 0
                  answers_per_day: null
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/analytics/entity:
    get:
      operationId: adminGetEntityKeyAnalytics
      summary: Get entity key analytics
      description: Returns analytics aggregated by entity key (e.g., country, theme, etc.).
      tags:
      - Admin Analytics
      security:
      - BearerAuth: []
      parameters:
      - name: entity_type
        in: query
        schema:
          type: string
        description: Entity type to aggregate by
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
        description: Number of results
      responses:
        200:
          description: Entity analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
              example:
                data: []
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/analytics/geography/countries:
    get:
      operationId: adminGetGeoCountryStats
      summary: Get geography country stats
      description: Returns analytics grouped by country for geography mode games.
      tags:
      - Admin Analytics
      security:
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      responses:
        200:
          description: Analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
              example:
                data: []
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/analytics/geography/countries-summary:
    get:
      operationId: adminGetCountriesSummary
      summary: Get countries summary analytics
      description: Returns a summary of performance stats across all countries.
      tags:
      - Admin Analytics
      security:
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      responses:
        200:
          description: Analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
              example:
                data: []
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/analytics/geography/questions:
    get:
      operationId: adminGetGeographyQuestionStats
      summary: Get geography question stats
      description: Returns analytics for geography-type questions.
      tags:
      - Admin Analytics
      security:
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      responses:
        200:
          description: Analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
              example:
                data: []
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/analytics/geography/variants:
    get:
      operationId: adminGetGeographyVariantStats
      summary: Get geography variant stats
      description: Returns stats grouped by geography game variant (flag variants, etc.).
      tags:
      - Admin Analytics
      security:
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      responses:
        200:
          description: Analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
              example:
                data: []
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/analytics/geography/country/{slug}:
    get:
      operationId: adminGetCountryAnalytics
      summary: Get country analytics
      description: Returns detailed analytics for a specific country (success rates, avg time, play count).
      tags:
      - Admin Analytics
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: Country slug (e.g. france)
        example: france
      responses:
        200:
          description: Country analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties: true
              example:
                data:
                  slug: france
                  total_answers: 0
                  success_rate: 0
                  avg_time_ms: 0
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/analytics/geography/country/{slug}/games:
    get:
      operationId: adminGetCountryGames
      summary: Get games for a country
      description: Returns game statistics for questions involving a specific country.
      tags:
      - Admin Analytics
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: Country slug
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: Game stats for country
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
              example:
                data: []
        401:
          $ref: '#/components/responses/Unauthorized'
403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/stats/performance:
    get:
      operationId: adminGetGamePerformanceStats
      summary: Get game performance stats
      description: Returns performance statistics for games (avg duration, completion rate, score distributions).
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      responses:
        200:
          description: Game performance stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties: true
              example:
                data:
                  avg_duration_seconds: 0
                  completion_rate: 0
                  abandonment_rate: 0
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/reports/{id}/status:
    patch:
      operationId: adminUpdateReportStatus
      summary: Update report status
      description: Updates the status of a question report (pending → in_progress → resolved).
      tags:
      - Admin Reports
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Report UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReportStatus'
            example:
              status: resolved
              resolution_notes: Question corrected.
      responses:
        200:
          description: Report updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Report'
              example:
                data:
                  id: 00000000-0000-0000-0000-000000000000
                  status: resolved
                  resolution_notes: Question corrected.
                  created_at: '2026-04-11T12:00:00Z'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/reports:
    get:
      operationId: adminListReports
      summary: List all reports
      tags:
      - Admin Reports
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - in: query
        name: status
        schema:
          type: string
          enum:
          - pending
          - in_progress
          - resolved
        description: Filter by status
      responses:
        '200':
          description: Reports list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 00000000-0000-0000-0000-000000000001
                  question_id: d311236a-441a-4379-b3ce-54cdc5364195
                  reporter_id: 550e8400-e29b-41d4-a716-446655440010
                  status: pending
                  reason: incorrect_answer
                  created_at: '2026-04-11T12:00:00Z'
                pagination:
                  total: 1
                  limit: 50
                  offset: 0
                  has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/reports/{id}:
    get:
      operationId: adminGetReport
      summary: Get report
      tags:
      - Admin Reports
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: Report UUID
      responses:
        '200':
          description: Report details
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  id: 00000000-0000-0000-0000-000000000001
                  question_id: d311236a-441a-4379-b3ce-54cdc5364195
                  reporter_id: 550e8400-e29b-41d4-a716-446655440010
                  status: pending
                  reason: incorrect_answer
                  description: The answer marked as correct is actually wrong
                  created_at: '2026-04-11T12:00:00Z'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/games:
    get:
      operationId: adminListGames
      summary: List all games
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - in: query
        name: status
        schema:
          type: string
          enum:
          - waiting
          - ready
          - in_progress
          - completed
          - cancelled
          - abandoned
        description: Filter by game status
      - in: query
        name: mode
        schema:
          type: string
          enum:
          - solo
          - 1v1
          - multi
      responses:
        '200':
          description: Games list
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - id: 7a2a94a1-9320-40a9-a010-552ffaa4d722
                  public_id: gm-abc123
                  mode: 1v1
                  status: completed
                  creator_public_id: '#20483-18393'
                  question_count: 10
                  created_at: '2025-04-10T10:00:00Z'
                  completed_at: '2025-04-10T10:05:00Z'
                pagination:
                  total: 100
                  limit: 50
                  offset: 0
                  has_more: true
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/stats:
    get:
      operationId: adminGetGameStats
      summary: Get game statistics
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Game statistics
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  total_games: 1500
                  active_games: 12
                  completed_games: 1480
                  avg_duration_seconds: 300
                  completion_rate: 0.95
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}:
    get:
      operationId: adminGetGameByID
      summary: Get game by ID
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Game'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: adminDeleteGameByID
      summary: Delete game
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Game deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}/players:
    get:
      operationId: adminGetGamePlayers
      summary: Get game players
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game players
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440001
                  game_id: 7a2a94a1-9320-40a9-a010-552ffaa4d722
                  user_id: 550e8400-e29b-41d4-a716-446655440010
                  score: 800
                  is_ready: true
                  status: completed
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}/questions:
    get:
      operationId: adminGetGameQuestions
      summary: Get game questions
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game questions
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}/answers:
    get:
      operationId: adminGetGameAnswers
      summary: Get game answers
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game answers
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}/cancel:
    post:
      operationId: adminCancelGame
      summary: Cancel game
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game cancelled
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}/archive:
    post:
      operationId: adminArchiveGame
      summary: Archive game
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game archived
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/{id}/unarchive:
    post:
      operationId: adminUnarchiveGame
      summary: Unarchive game
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Game unarchived
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/invites:
    get:
      operationId: adminListGameInvites
      summary: List game invites
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Game invites
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - id: 550e8400-e29b-41d4-a716-446655440001
                  game_id: 7a2a94a1-9320-40a9-a010-552ffaa4d722
                  from_user_id: 550e8400-e29b-41d4-a716-446655440010
                  to_user_id: 550e8400-e29b-41d4-a716-446655440020
                  status: pending
                pagination:
                  total: 5
                  limit: 50
                  offset: 0
                  has_more: false
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/invites/pending:
    get:
      operationId: adminListPendingInvites
      summary: List pending invites
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Pending invites
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/invites/{inviteID}:
    delete:
      operationId: adminDeleteGameInvite
      summary: Delete game invite
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: inviteID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Invite deleted
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/invites/{inviteID}/cancel:
    post:
      operationId: adminCancelGameInvite
      summary: Cancel game invite
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: inviteID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Invite cancelled
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/stats/modes:
    get:
      operationId: adminGetGameModeStats
      summary: Get game mode statistics
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Mode statistics
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  solo:
                    games: 500
                    avg_score: 650
                  onevone:
                    games: 800
                    avg_score: 780
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/stats/daily:
    get:
      operationId: adminGetDailyGameStats
      summary: Get daily game statistics
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: days
        schema:
          type: integer
          default: 30
      responses:
        '200':
          description: Daily statistics
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - date: '2025-04-10'
                  games: 45
                  players: 80
                  avg_score: 720
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/stats/users/{userID}:
    get:
      operationId: adminGetUserGameStats
      summary: Get user game statistics
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User game stats
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  total_games: 50
                  games_won: 35
                  games_lost: 15
                  avg_score: 780
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/users/{userID}:
    get:
      operationId: adminGetUserGameHistory
      summary: Get user game history
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      parameters:
      - in: path
        name: userID
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: User game history
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/stats/performance:
    get:
      operationId: adminGetGamePerformanceStats
      summary: Get game performance stats
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Performance stats
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  avg_duration_seconds: 300
                  completion_rate: 0.95
                  abandonment_rate: 0.03
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/cleanup:
    post:
      operationId: adminCleanupAbandonedGames
      summary: Cleanup abandoned games
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Cleanup completed
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  cleaned: 15
                  message: 15 abandoned games cleaned up
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/games/maintenance:
    post:
      operationId: adminRunGameMaintenance
      summary: Run game maintenance
      tags:
      - Admin Games
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Maintenance completed
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                  processed: 100
                  message: Game maintenance completed
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
  /api/v1/admin/pods:
    get:
      operationId: adminGetAllPods
      summary: List all pods
      description: |
        Returns the list of all running pods discovered via Redis heartbeats, along with
        aggregated metadata (total clients, online users, active games, pod type counts).
        Each pod publishes a heartbeat every 5 seconds with a 15-second TTL; pods that
        miss three consecutive heartbeats are automatically evicted from the list.
        The `is_current` flag identifies the pod that handled this HTTP request.
      tags:
      - Admin Pods
      security:
      - BearerAuth: []
      responses:
        200:
          description: Pod list with aggregated metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pods:
                        type: array
                        items:
                          $ref: '#/components/schemas/PodInfo'
                      meta:
                        $ref: '#/components/schemas/PodsMeta'
              example:
                data:
                  pods:
                  - pod_id: 88e4f348-e5c7-4259-a661-59dc22f0e872
                    pod_type: main
                    status: healthy
                    is_current: false
                    connected_clients: 1
                    online_users: 1
                    active_games: 0
                    last_heartbeat: '2026-04-24T09:30:36.394930651Z'
                    started_at: '2026-04-24T09:09:06.389483275Z'
                  - pod_id: 82747620-4692-42ee-b0ac-2591632696f3
                    pod_type: headless
                    status: healthy
                    is_current: false
                    connected_clients: 0
                    online_users: 0
                    active_games: 0
                    last_heartbeat: '2026-04-24T09:30:36.637710577Z'
                    started_at: '2026-04-24T09:09:06.636588936Z'
                  meta:
                    total_pods: 2
                    main_pods: 1
                    headless_pods: 1
                    total_clients: 1
                    total_users: 1
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        500:
          $ref: '#/components/responses/InternalError'
  /api/v1/geography/flags/{country_code}/png/{format}:
    get:
      operationId: getFlagPNG
      summary: Get flag as PNG
      description: Returns a country flag as a PNG image in the specified size format (512 or 1024).
      tags:
      - Geography
      security:
      - BearerAuth: []
      parameters:
      - name: country_code
        in: path
        required: true
        schema:
          type: string
        description: ISO 3166-1 alpha-2 country code (e.g. FR)
        example: FR
      - name: format
        in: path
        required: true
        schema:
          type: string
          enum:
          - '512'
          - '1024'
        description: PNG size (512 or 1024 pixels)
        example: '512'
      responses:
        200:
          description: PNG image
          content:
            image/png:
              schema:
                type: string
                format: binary
            application/json:
              example: null
        404:
          $ref: '#/components/responses/NotFound'
        401:
          $ref: '#/components/responses/Unauthorized'
  /api/v1/games/{gameID}/questions/{number}/report:
    post:
      operationId: reportGameQuestion
      summary: Report a game question
      description: Creates a report for a question encountered during a game session (using question number, not ID).
      tags:
      - Games
      security:
      - BearerAuth: []
      parameters:
      - name: gameID
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Game UUID
      - name: number
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
        description: Question number within the game (1-indexed)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGameReportRequest'
            example:
              reason: wrong_answer
              message: The correct answer should be Paris, not Lyon.
      responses:
        201:
          description: Report created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Report'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          description: Already reported this question
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CONFLICT
                  message: question already reported by this user