{
  "openapi": "3.1.0",
  "info": {
    "title": "CalculationTime public machine-readable surface",
    "version": "2026-09-26",
    "summary": "Static calculator discovery, citation, and answer-engine contract for CalculationTime.",
    "description": "This public contract documents the currently crawlable CalculationTime website surface: calculator pages, sitemap, robots, plugin manifest, glossary, developer pages, and static answer-engine hooks. Dynamic ?format=json calculator output is intentionally not advertised here until a runtime endpoint exists."
  },
  "servers": [
    {
      "url": "https://www.calculationtime.com",
      "description": "Public CalculationTime website"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Machine-readable discovery documents for crawlers and agents."
    },
    {
      "name": "Calculators",
      "description": "Canonical static calculator pages with visible formulas, default results, schema, and semantic hooks."
    },
    {
      "name": "Authority",
      "description": "Trust, glossary, source policy, and developer reference pages."
    }
  ],
  "paths": {
    "/openapi.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Download the public CalculationTime OpenAPI contract",
        "operationId": "getPublicOpenApiContract",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 contract.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDocument"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/ai-plugin.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Download the CalculationTime AI plugin manifest",
        "operationId": "getAiPluginManifest",
        "responses": {
          "200": {
            "description": "AI plugin manifest for agent discovery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiPluginManifest"
                }
              }
            }
          }
        }
      }
    },
    "/manifest.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Download the CalculationTime PWA manifest",
        "operationId": "getPwaManifest",
        "responses": {
          "200": {
            "description": "Web app manifest.",
            "content": {
              "application/manifest+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/calculator-catalog.json": {
      "get": {
        "tags": ["Discovery", "Calculators"],
        "summary": "Download the static calculator catalog for agents and crawlers",
        "operationId": "getCalculatorCatalog",
        "responses": {
          "200": {
            "description": "Static catalog of calculator slugs, canonical URLs, formulas, input metadata, default states, and runtime boundaries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculatorCatalog"
                }
              }
            }
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Read crawler access policy",
        "operationId": "getRobotsTxt",
        "responses": {
          "200": {
            "description": "robots.txt with AI crawler access and sitemap reference.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Read the canonical XML sitemap",
        "operationId": "getSitemap",
        "responses": {
          "200": {
            "description": "XML sitemap for indexable pages.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Read the LLM-oriented site summary",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "LLM-oriented summary of important site surfaces.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/calculators/{slug}/": {
      "get": {
        "tags": ["Calculators"],
        "summary": "Read a canonical calculator page",
        "operationId": "getCalculatorPage",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Canonical calculator slug, for example length-converter or crux-perpetual.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Static HTML calculator page with formula, assumptions, default result preview, schema, and data-ai-context hooks.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "308": {
            "description": "Legacy or duplicate calculator route redirected to the current survivor page."
          },
          "404": {
            "description": "No published calculator page exists for the slug."
          }
        },
        "x-calculationtime-ai-hooks": [
          "data-ai-context=\"calculator-answer-summary\"",
          "data-ai-context=\"direct-answer\"",
          "data-ai-context=\"how-to-steps\"",
          "data-ai-context=\"default-result\"",
          "data-ai-context=\"ai-prompt-library\""
        ]
      }
    },
    "/tools/": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Browse the All Tools directory",
        "operationId": "getAllToolsDirectory",
        "responses": {
          "200": {
            "description": "Cleaned public directory of current CalculationTime tools.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/glossary/": {
      "get": {
        "tags": ["Authority"],
        "summary": "Read the CalculationTime glossary",
        "operationId": "getGlossary",
        "responses": {
          "200": {
            "description": "Glossary of calculator, time, and celestial terms.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/developers/api/": {
      "get": {
        "tags": ["Authority"],
        "summary": "Read developer API overview",
        "operationId": "getDeveloperApiOverview",
        "responses": {
          "200": {
            "description": "Human-readable developer API overview and beta boundaries.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OpenApiDocument": {
        "type": "object",
        "description": "OpenAPI 3.1 document."
      },
      "AiPluginManifest": {
        "type": "object",
        "required": ["schema_version", "name_for_human", "name_for_model", "auth", "api"],
        "properties": {
          "schema_version": { "type": "string" },
          "name_for_human": { "type": "string" },
          "name_for_model": { "type": "string" },
          "description_for_human": { "type": "string" },
          "description_for_model": { "type": "string" },
          "auth": { "type": "object" },
          "api": { "type": "object" },
          "logo_url": { "type": "string", "format": "uri" },
          "contact_email": { "type": "string" },
          "legal_info_url": { "type": "string", "format": "uri" }
        }
      },
      "CalculatorCatalog": {
        "type": "object",
        "required": ["schemaVersion", "site", "runtimeBoundary", "calculators"],
        "properties": {
          "schemaVersion": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "site": { "type": "string", "format": "uri" },
          "runtimeBoundary": { "type": "object" },
          "agentUsage": { "type": "object" },
          "totals": { "type": "object" },
          "calculators": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["slug", "name", "canonicalUrl"],
              "properties": {
                "slug": { "type": "string" },
                "name": { "type": "string" },
                "canonicalUrl": { "type": "string", "format": "uri" },
                "category": { "type": ["string", "null"] },
                "status": { "type": "string" },
                "description": { "type": ["string", "null"] },
                "directAnswer": { "type": ["string", "null"] },
                "formulaText": { "type": ["string", "null"] },
                "inputs": { "type": "array" },
                "defaultState": { "type": "object" },
                "assumptions": { "type": "array" },
                "workedExample": { "type": ["string", "null"] },
                "keywords": { "type": "array" }
              }
            }
          }
        }
      }
    }
  },
  "x-calculationtime-runtime-boundary": {
    "formatJsonCalculatorOutput": "planned-not-live",
    "reason": "The production site is currently a static export. Calculator pages expose default solved states, semantic hooks, schema, and visible formulas, but arbitrary user-input JSON output needs a runtime endpoint before it is advertised."
  }
}