openapi: 3.1.0
info:
  title: FusionHub FUSION LAUNCHER Public API
  description: Official public API for FusionHub FUSION LAUNCHER services including
    real-time operational status, update delivery, community Minecraft multiplayer
    server registry, and supported game version matrices.
  version: 1.0.0
  contact:
    name: FusionHub Developer Relations & Support
    email: support@fusionhub.in
    url: https://minecraft.fusionhub.in/contact
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-deprecation-policy:
    policy_url: https://minecraft.fusionhub.in/docs#deprecation
    notice_period: 12 months
    sunset_header: Sunset
    deprecation_header: Deprecation
servers:
- url: https://minecraft.fusionhub.in
  description: Production Global Edge Network
paths:
  /api/v1/status.json:
    get:
      summary: Get system operational status
      description: Retrieves infrastructure health metrics, uptime indicators, and
        microservice status for FUSION Launcher.
      operationId: getSystemStatus
      tags:
      - Health & Status
      parameters:
      - name: service
        in: query
        required: false
        description: Filter by specific service name (e.g. cloud_sync, api, updates).
        schema:
          type: string
          default: all
          enum:
          - all
          - cloud_sync
          - api
          - updates
      - name: format
        in: query
        required: false
        description: Response format representation.
        schema:
          type: string
          default: json
          enum:
          - json
      responses:
        '200':
          description: Operational status of FUSION Launcher infrastructure
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - service
                - version
                - environment
                - cloud_sync
                - timestamp
                properties:
                  status:
                    type: string
                    example: operational
                  service:
                    type: string
                    example: fusion-launcher-api
                  version:
                    type: string
                    example: 2.0.5
                  environment:
                    type: string
                    example: production
                  cloud_sync:
                    type: string
                    example: active
                  timestamp:
                    type: string
                    format: date-time
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad Request or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server or service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/update.json:
    get:
      summary: Get latest launcher update
      description: Retrieves latest production release version, download URL, changelog
        notes, and minimum system requirements.
      operationId: getLatestLauncherUpdate
      tags:
      - Distribution
      parameters:
      - name: channel
        in: query
        required: false
        description: Release channel to check (stable or beta).
        schema:
          type: string
          default: stable
          enum:
          - stable
          - beta
      - name: platform
        in: query
        required: false
        description: Target operating system platform.
        schema:
          type: string
          default: windows
          enum:
          - windows
          - macos
          - linux
      responses:
        '200':
          description: Current release update payload
          content:
            application/json:
              schema:
                type: object
                required:
                - version
                - title
                - download_url
                - file_name
                - mandatory
                - release_date
                properties:
                  version:
                    type: string
                    example: 2.0.5
                  title:
                    type: string
                    example: FUSION LAUNCHER v2.0.5 Stable Release
                  message:
                    type: string
                  download_url:
                    type: string
                    format: uri
                  file_name:
                    type: string
                    example: FUSION LAUNCHER Setup 2.0.5.exe
                  mandatory:
                    type: boolean
                    example: false
                  release_date:
                    type: string
                    format: date
                  runtime:
                    type: string
                    example: Java 25 Bundled (OpenJDK)
        '400':
          description: Bad Request or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server or service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/servers.json:
    get:
      summary: Get community Minecraft servers
      description: Retrieves the curated directory of verified Minecraft multiplayer
        servers registered on FusionHub.
      operationId: getCommunityServers
      tags:
      - Servers
      parameters:
      - name: category
        in: query
        required: false
        description: Filter servers by gameplay category.
        schema:
          type: string
          default: all
          enum:
          - all
          - survival
          - pvp
          - creative
          - minigames
          - smp
      - name: limit
        in: query
        required: false
        description: Maximum number of servers to return in the list.
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Directory of active Minecraft community servers
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - servers
                properties:
                  count:
                    type: integer
                    example: 2
                  servers:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - ip
                      - version
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        ip:
                          type: string
                        version:
                          type: string
                        description:
                          type: string
                        online_players:
                          type: integer
                        max_players:
                          type: integer
                        verified:
                          type: boolean
        '400':
          description: Bad Request or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server or service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/versions.json:
    get:
      summary: Get supported Minecraft versions and loaders
      description: Returns supported Minecraft release versions, compatible Fabric,
        Forge, and Quilt loaders, and Java runtime requirements.
      operationId: getSupportedVersions
      tags:
      - Versions
      parameters:
      - name: loader
        in: query
        required: false
        description: Filter version support matrix by mod loader.
        schema:
          type: string
          default: all
          enum:
          - all
          - fabric
          - forge
          - quilt
          - vanilla
      responses:
        '200':
          description: Supported Minecraft game versions and loaders
          content:
            application/json:
              schema:
                type: object
                required:
                - latest_release
                - bundled_java
                - supported_releases
                - loaders
                properties:
                  latest_release:
                    type: string
                    example: '26.2'
                  bundled_java:
                    type: string
                    example: Java 25 (OpenJDK 25.0.2)
                  supported_releases:
                    type: array
                    items:
                      type: string
                  loaders:
                    type: object
                    required:
                    - fabric
                    - forge
                    - quilt
                    properties:
                      fabric:
                        type: string
                        example: 0.19.5
                      forge:
                        type: string
                        example: 65.1.0
                      quilt:
                        type: string
                        example: 0.31.0
        '400':
          description: Bad Request or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server or service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - status
          - message
          - hint
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            status:
              type: integer
              example: 404
            message:
              type: string
              example: The requested resource was not found.
            hint:
              type: string
              example: Verify the endpoint against https://minecraft.fusionhub.in/openapi.json
                or documentation at https://minecraft.fusionhub.in/docs.
            docs_url:
              type: string
              format: uri
              example: https://minecraft.fusionhub.in/docs
            openapi_url:
              type: string
              format: uri
              example: https://minecraft.fusionhub.in/openapi.json