openapi: "3.0.0"
info:
  title: "Babbage Calculator"
  description: >
    The world's most comprehensive suite of free, instant digital calculators.
    Over 900 calculators across Finance, Construction, Health, Engineering, Physics,
    Chemistry, Medical, Sports, and 80+ categories. All calculations are performed
    entirely client-side for zero latency and maximum privacy.
  version: "1.0.0"
  contact:
    email: "hello@babbagecalculator.com"
    url: "https://babbagecalculator.com"
servers:
  - url: "https://babbagecalculator.com"
    description: "Production"
paths:
  /api/v1/calculate/{slug}:
    post:
      operationId: executeCalculation
      summary: "Execute an exact calculator and return JSON results"
      description: >
        Programmatically execute a Babbage Calculator and receive JSON results.
        Payload keys must match the expected inputs documented in llms-full.txt.
        Currently rate-limited to 60 requests per minute per IP.
      parameters:
        - name: slug
          in: path
          required: true
          description: "The URL slug of the calculator (e.g. 'mortgage-payment-calculator')"
          schema:
            type: string
      requestBody:
        description: "Key-value pairs of input fields"
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: "Calculation results"
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      primary:
                        type: object
                      secondary:
                        type: array
        "429":
          description: "Too Many Requests - Rate limit exceeded"
  /calculator/{slug}:
    get:
      operationId: getCalculator
      summary: "Load a specific interactive calculator by its slug"
      description: >
        Returns an interactive calculator page where users can input values
        and receive instant, client-side calculations. Each calculator includes
        step-by-step breakdowns, FAQs, and related calculators.
      parameters:
        - name: slug
          in: path
          required: true
          description: "The URL slug of the calculator (e.g. 'mortgage-payment-calculator')"
          schema:
            type: string
      responses:
        "200":
          description: "Interactive calculator page with inputs, results, and educational content"
  /category/{category}:
    get:
      operationId: getCategoryCalculators
      summary: "Browse all calculators in a specific category"
      parameters:
        - name: category
          in: path
          required: true
          description: "The category slug (e.g. 'finance', 'construction', 'medical')"
          schema:
            type: string
      responses:
        "200":
          description: "Category page listing all available calculators"
  /calculators:
    get:
      operationId: getAllCalculators
      summary: "Browse the complete directory of all calculators"
      responses:
        "200":
          description: "Full directory page with search and filtering"
  /llms.txt:
    get:
      operationId: getCalculatorIndex
      summary: "Machine-readable index of all calculators with descriptions"
      description: "Returns a Markdown-formatted list of all calculators with direct URLs and short descriptions. Optimised for LLM token efficiency."
      responses:
        "200":
          description: "Plain text Markdown list of all calculators"
          content:
            text/plain:
              schema:
                type: string
  /llms-full.txt:
    get:
      operationId: getCalculatorFullIndex
      summary: "Comprehensive machine-readable specification of all calculators"
      description: "Returns detailed specifications for every calculator including input fields, formulas, categories, and FAQs. Designed for deep LLM ingestion."
      responses:
        "200":
          description: "Plain text Markdown with full calculator specifications"
          content:
            text/plain:
              schema:
                type: string
  /sitemap.xml:
    get:
      operationId: getSitemap
      summary: "XML sitemap with all page URLs"
      responses:
        "200":
          description: "Standard XML sitemap"