openapi: 3.1.0
info:
  title: Everwinders API
  description: Public endpoints for Everwinders - Everwind gaming community platform. Provides AI-readable data, server listings, plugins, articles, and community content.
  version: '2.0'
  contact:
    url: https://everwinders.com/contact

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

paths:
  /ai/summary.json:
    get:
      summary: Site overview and structure
      description: Returns structured site information, navigation, statistics, and AI endpoint list.
      operationId: getAiSummary
      tags: [AI Endpoints]
      responses:
        '200':
          description: Site summary
          content:
            application/json:
              schema:
                type: object

  /ai/facts.json:
    get:
      summary: Live statistics and verifiable facts
      description: Returns real-time database statistics, popular servers, popular plugins, and categories.
      operationId: getAiFacts
      tags: [AI Endpoints]
      responses:
        '200':
          description: Facts dataset
          content:
            application/json:
              schema:
                type: object

  /ai/faq.json:
    get:
      summary: Structured FAQ data
      description: Returns frequently asked questions grouped by category with structured answers.
      operationId: getAiFaq
      tags: [AI Endpoints]
      responses:
        '200':
          description: FAQ data
          content:
            application/json:
              schema:
                type: object

  /ai/actions.json:
    get:
      summary: Available agentic actions
      description: Lists all actions an AI agent can perform on this site - search, browse, retrieve data.
      operationId: getAiActions
      tags: [AI Endpoints]
      responses:
        '200':
          description: Actions list
          content:
            application/json:
              schema:
                type: object

  /ai/contact.json:
    get:
      summary: Contact and escalation endpoint
      description: Provides contact information for fact verification and data correction requests.
      operationId: getAiContact
      tags: [AI Endpoints]
      responses:
        '200':
          description: Contact data
          content:
            application/json:
              schema:
                type: object

  /entity/disambiguation.json:
    get:
      summary: Entity disambiguation data
      description: Returns unique identifiers and context signals for cross-AI knowledge graph alignment.
      operationId: getEntityDisambiguation
      tags: [AI Endpoints]
      responses:
        '200':
          description: Entity data
          content:
            application/json:
              schema:
                type: object

  /ai-license.json:
    get:
      summary: AI usage license policy
      description: Legal policy defining inference, training, and attribution requirements for AI models.
      operationId: getAiLicense
      tags: [Legal]
      responses:
        '200':
          description: License policy
          content:
            application/json:
              schema:
                type: object

  /ai-transparency.json:
    get:
      summary: AI transparency report
      description: Machine-readable transparency report for regulatory compliance.
      operationId: getAiTransparency
      tags: [Legal]
      responses:
        '200':
          description: Transparency report
          content:
            application/json:
              schema:
                type: object

  /servers:
    get:
      summary: Browse game servers
      operationId: listServers
      tags: [Public Pages]
      responses:
        '200':
          description: Server listing page (HTML)

  /server/{slug}:
    get:
      summary: Server detail page
      operationId: getServer
      tags: [Public Pages]
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Server detail (HTML)

  /plugins:
    get:
      summary: Browse plugins
      operationId: listPlugins
      tags: [Public Pages]
      responses:
        '200':
          description: Plugin listing page (HTML)

  /plugins/{slug}:
    get:
      summary: Plugin detail page
      operationId: getPlugin
      tags: [Public Pages]
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plugin detail (HTML)

  /blog:
    get:
      summary: Browse articles
      operationId: listArticles
      tags: [Public Pages]
      responses:
        '200':
          description: Blog listing page (HTML)

  /blog/{slug}:
    get:
      summary: Article detail page
      operationId: getArticle
      tags: [Public Pages]
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Article detail (HTML)

  /search:
    get:
      summary: Global search
      operationId: globalSearch
      tags: [Public Pages]
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Search results (HTML)

  /sitemap.xml:
    get:
      summary: XML Sitemap index
      operationId: getSitemap
      tags: [SEO]
      responses:
        '200':
          description: Sitemap index
          content:
            application/xml:
              schema:
                type: string

  /feed.rss:
    get:
      summary: RSS Feed
      operationId: getRssFeed
      tags: [Feeds]
      responses:
        '200':
          description: RSS 2.0 feed
          content:
            application/rss+xml:
              schema:
                type: string

  /llms.txt:
    get:
      summary: LLM context file
      operationId: getLlmsTxt
      tags: [AI Endpoints]
      responses:
        '200':
          description: Markdown context for LLM
          content:
            text/plain:
              schema:
                type: string

  /llms-full.txt:
    get:
      summary: Full site content for RAG
      operationId: getLlmsFullTxt
      tags: [AI Endpoints]
      responses:
        '200':
          description: Full Markdown export
          content:
            text/markdown:
              schema:
                type: string

tags:
  - name: AI Endpoints
    description: Machine-readable endpoints for AI crawlers and agents
  - name: Public Pages
    description: Human-readable web pages
  - name: Feeds
    description: Content syndication feeds
  - name: SEO
    description: Search engine optimization files
  - name: Legal
    description: Legal and compliance endpoints