openapi: 3.1.0
info:
  title: AI Economy Hub Public Data API
  version: "1.0.0"
  description: |
    Free public REST API for AI model pricing, ROI math, automation cost
    models, and 2026 AI-economy benchmark data. CORS-open, edge-cached,
    no auth. CC-BY-4.0 license — attribution = a link back to the canonical
    page. Human-readable docs: https://aieconomyhub.co/api/docs
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: AI Economy Hub
    url: https://aieconomyhub.co
servers:
  - url: https://aieconomyhub.co
paths:
  /api/page:
    get:
      summary: List every calculator
      operationId: listCalculators
      responses:
        "200":
          description: Index of calculator slugs + categories
          content:
            application/json:
              schema:
                type: object
                properties:
                  count: { type: integer }
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/CalcSummary" }
                  categories:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        label: { type: string }
                  docs: { type: string, format: uri }
                  attribution: { $ref: "#/components/schemas/Attribution" }
  /api/page/{slug}:
    get:
      summary: Get one calculator's structured payload
      operationId: getCalculator
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Full payload for one calculator
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CalcPayload" }
        "404":
          description: Slug not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  message: { type: string }
                  hint: { type: string }
components:
  schemas:
    Attribution:
      type: object
      properties:
        canonicalUrl: { type: string, format: uri }
        requirement: { type: string }
        license: { type: string }
    CalcSummary:
      type: object
      properties:
        slug: { type: string }
        title: { type: string }
        description: { type: string }
        category: { type: string }
        kind: { type: string }
        top: { type: boolean }
        url: { type: string, format: uri }
        apiUrl: { type: string, format: uri }
    CalcPayload:
      type: object
      properties:
        slug: { type: string }
        title: { type: string }
        h1: { type: string }
        shortTitle: { type: string }
        description: { type: string }
        url: { type: string, format: uri }
        apiUrl: { type: string, format: uri }
        category:
          type: object
          properties:
            id: { type: string }
            label: { type: string }
        kind: { type: string }
        top: { type: boolean }
        lastUpdated: { type: string, format: date }
        faqs:
          type: array
          items:
            type: object
            properties:
              q: { type: string }
              a: { type: string }
        howto:
          oneOf:
            - type: "null"
            - type: object
              properties:
                name: { type: string }
                description: { type: string }
                steps:
                  type: array
                  items:
                    type: object
                    properties:
                      name: { type: string }
                      text: { type: string }
        dataset:
          oneOf:
            - type: "null"
            - type: object
              properties:
                name: { type: string }
                description: { type: string }
                columnNames:
                  type: array
                  items: { type: string }
        relatedTools:
          type: array
          items:
            type: object
            properties:
              slug: { type: string }
              title: { type: string }
              url: { type: string, format: uri }
              apiUrl: { type: string, format: uri }
        attribution: { $ref: "#/components/schemas/Attribution" }
