openapi: 3.1.0
info:
  title: Everwind Servers API
  description: REST API for Everwind Servers - Game server listing platform. Provides access to game servers, plugins, blogs, and community data.
  version: "1.0.0"
  contact:
    email: 
    url: https://everwind-servers.com/contact
  license:
    name: Proprietary
    url: https://everwind-servers.com/.well-known/ai-license.json

servers:
  - url: https://everwind-servers.com
    description: Production server

paths:
  /api/servers:
    get:
      summary: List game servers
      description: Get a paginated list of active game servers with optional filtering
      operationId: listServers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: category
          in: query
          schema:
            type: string
          description: Filter by category slug (e.g. minecraft, hytale, cs2)
        - name: search
          in: query
          schema:
            type: string
          description: Search servers by name, description, or tags
        - name: sort
          in: query
          schema:
            type: string
            enum: [votes, newest, players, rating]
            default: votes
      responses:
        '200':
          description: Paginated list of servers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      per_page:
                        type: integer
                      current_page:
                        type: integer
                      last_page:
                        type: integer

  /api/servers/{slug}:
    get:
      summary: Get server details
      operationId: getServer
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Server details
        '404':
          description: Server not found

  /api/plugins:
    get:
      summary: List plugins
      operationId: listPlugins
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: q
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Plugin list

  /api/blogs:
    get:
      summary: List blog posts
      operationId: listBlogs
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: category
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Blog post list

  /api/blogs/{slug}:
    get:
      summary: Get blog post details
      operationId: getBlog
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Blog post details

  /api/categories:
    get:
      summary: List game categories
      operationId: listCategories
      responses:
        '200':
          description: Category list

  /api/faq:
    get:
      summary: Get FAQ
      operationId: getFaq
      responses:
        '200':
          description: FAQ list

  /api/recruitments:
    get:
      summary: List recruitment posts
      operationId: listRecruitments
      responses:
        '200':
          description: Recruitment list

  /api/ai/summary:
    get:
      summary: AI Summary
      description: Platform summary optimized for AI models
      operationId: getAiSummary
      responses:
        '200':
          description: Platform summary in Schema.org format

  /api/ai/facts:
    get:
      summary: AI Facts
      description: Key facts about the platform, citation-ready
      operationId: getAiFacts
      responses:
        '200':
          description: Array of facts with confidence levels

  /api/ai/faq:
    get:
      summary: AI FAQ
      description: FAQ in Schema.org FAQPage format
      operationId: getAiFaq
      responses:
        '200':
          description: FAQPage JSON-LD

  /api/ai/knowledge:
    get:
      summary: AI Knowledge Base
      description: Full knowledge base for AI RAG systems
      operationId: getAiKnowledge
      responses:
        '200':
          description: Complete knowledge base

  /api/health:
    get:
      summary: Health Check
      operationId: healthCheck
      responses:
        '200':
          description: Service health status