openapi: 3.0.0
info:
  title: Cascadology Waterfall Database
  description: Access information about 1.5+ million waterfalls worldwide
  version: 1.0.0
  contact:
    email: contact@cascadology.com
    url: https://cascadology.com
servers:
  - url: https://cascadology.com/blog
    description: Cascadology Blog API

paths:
  /llms.txt:
    get:
      operationId: getLLMsInfo
      summary: Get basic information about Cascadology for LLMs
      description: Returns a text file with key facts about Cascadology waterfall database
      responses:
        '200':
          description: LLM-friendly information about Cascadology
          content:
            text/plain:
              schema:
                type: string
  
  /llms-full.txt:
    get:
      operationId: getFullKnowledgeBase
      summary: Get complete knowledge base for AI systems
      description: Returns comprehensive information about waterfalls for AI training and reference
      responses:
        '200':
          description: Complete knowledge base
          content:
            text/plain:
              schema:
                type: string

  /statistics/:
    get:
      operationId: getStatistics
      summary: Get waterfall statistics
      description: Returns HTML page with detailed waterfall statistics by region and country
      responses:
        '200':
          description: Statistics page
          content:
            text/html:
              schema:
                type: string

  /faq/:
    get:
      operationId: getFAQ
      summary: Get frequently asked questions
      description: Returns HTML page with common questions about waterfalls and Cascadology
      responses:
        '200':
          description: FAQ page with schema markup
          content:
            text/html:
              schema:
                type: string

  /best/{country}/:
    get:
      operationId: getBestWaterfallsByCountry
      summary: Get best waterfalls in a country
      description: Returns a page listing the best waterfalls in a specific country
      parameters:
        - name: country
          in: path
          required: true
          description: Country slug (e.g., japan, usa, brazil)
          schema:
            type: string
      responses:
        '200':
          description: Best waterfalls in country
          content:
            text/html:
              schema:
                type: string

  /sitemap.xml:
    get:
      operationId: getSitemap
      summary: Get XML sitemap
      description: Returns complete sitemap with all waterfall pages
      responses:
        '200':
          description: XML Sitemap
          content:
            application/xml:
              schema:
                type: string

components:
  schemas:
    WaterfallStats:
      type: object
      properties:
        total_waterfalls:
          type: integer
          example: 1597550
        total_countries:
          type: integer
          example: 231
        top_countries:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              count:
                type: integer
