openapi: 3.1.0
info:
  title: HytaleServery.com API
  description: |
    Verejné API pre HytaleServery.com - slovenský a český server list pre hru Hytale.
    Všetky endpointy sú verejné a nevyžadujú autentifikáciu (okrem hlasovacích akcií).
    
    Pre AI agentov: Preferované formáty sú JSON a Markdown.
    Dáta sa aktualizujú každých 5 minút (server status) alebo denne (štatistiky).
  version: '2.0'
  contact:
    name: HytaleServery.com Support
    url: https://discord.gg/dY3vD9tEQZ
    email: soulstrikedevs@gmail.com
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://hytaleservery.com
    description: Production

paths:
  /ai/servers.json:
    get:
      operationId: get_servers_json
      summary: Zoznam všetkých schválených serverov v JSON
      description: Vráti kompletný zoznam serverov s metadátami, štatistikami a stavom
      tags:
        - servers
      responses:
        '200':
          description: Zoznam serverov
          content:
            application/json:
              schema:
                type: object
                properties:
                  servers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Server'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      online:
                        type: integer
                      lastUpdated:
                        type: string
                        format: date-time

  /ai/servers.txt:
    get:
      operationId: get_servers_text
      summary: Zoznam serverov v plain text pre RAG systémy
      description: Čistý textový formát optimalizovaný pre LLM spracovanie
      tags:
        - servers
      responses:
        '200':
          description: Textový zoznam serverov
          content:
            text/plain:
              schema:
                type: string

  /ai/server/{slug}.txt:
    get:
      operationId: get_server_detail_text
      summary: Detail konkrétneho servera v plain text
      tags:
        - servers
      parameters:
        - name: slug
          in: path
          required: true
          description: URL slug servera
          schema:
            type: string
      responses:
        '200':
          description: Detail servera
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Server nenájdený

  /ai/summary.json:
    get:
      operationId: get_platform_summary
      summary: Agregované štatistiky platformy
      tags:
        - statistics
      responses:
        '200':
          description: Súhrnné štatistiky
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformSummary'

  /ai/facts.json:
    get:
      operationId: get_platform_facts
      summary: Overené fakty pre citácie
      description: Citovateľné fakty s confidence score pre AI modely
      tags:
        - statistics
      responses:
        '200':
          description: Zoznam faktov
          content:
            application/json:
              schema:
                type: object
                properties:
                  facts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Fact'

  /ai/faq.json:
    get:
      operationId: get_faq
      summary: Často kladené otázky
      tags:
        - content
      responses:
        '200':
          description: FAQ
          content:
            application/json:
              schema:
                type: object
                properties:
                  questions:
                    type: array
                    items:
                      type: object
                      properties:
                        question:
                          type: string
                        answer:
                          type: string

  /ai/contact.json:
    get:
      operationId: get_contact_info
      summary: Kontaktné údaje a eskalačný bod
      tags:
        - meta
      responses:
        '200':
          description: Kontaktné údaje
          content:
            application/json:
              schema:
                type: object

  /ai/markdown/{page}:
    get:
      operationId: get_markdown_content
      summary: Obsah stránky v Markdown formáte
      description: Clean Markdown verzia stránky pre LLM spracovanie
      tags:
        - content
      parameters:
        - name: page
          in: path
          required: true
          description: Názov stránky (homepage, servers, faq)
          schema:
            type: string
            enum: [homepage, servers, faq]
      responses:
        '200':
          description: Markdown obsah
          content:
            text/markdown:
              schema:
                type: string

  /servery:
    get:
      operationId: search_servers
      summary: Vyhľadať servery podľa kritérií
      tags:
        - servers
      parameters:
        - name: q
          in: query
          required: false
          description: Vyhľadávací výraz
          schema:
            type: string
        - name: mode
          in: query
          required: false
          description: Herný režim
          schema:
            type: string
            enum: [survival, creative, pvp, roleplay, adventure, minigames]
        - name: page
          in: query
          required: false
          description: Číslo stránky
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: HTML stránka so zoznamom serverov

components:
  schemas:
    Server:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        ip_address:
          type: string
        port:
          type: integer
        game_mode:
          type: string
        players_online:
          type: integer
        max_players:
          type: integer
        is_online:
          type: boolean
        uptime_percent:
          type: number
        votes_count:
          type: integer
        url:
          type: string

    PlatformSummary:
      type: object
      properties:
        name:
          type: string
        totalServers:
          type: integer
        onlineServers:
          type: integer
        totalVotes:
          type: integer
        averageUptime:
          type: number
        lastUpdated:
          type: string
          format: date-time

    Fact:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
        confidence:
          type: number
        source:
          type: string
        citeable:
          type: boolean
