{
  "openapi": "3.0.3",
  "info": {
    "title": "Quizzman Calendar API",
    "description": "Deterministic astronomical calendar engine: solar↔lunar (VN UTC+7 / CN UTC+8), VSOP87 solar terms, Jean Meeus / Hồ Ngọc Đức new moon, Can Chi, True Solar Time, NASA parity self-check. Not LLM-generated dates. Preferred docs: https://insight.quizzman.com/tool/about-calendar.md",
    "version": "1.0.0",
    "contact": {
      "name": "Quizzman",
      "url": "https://quizzman.com/"
    }
  },
  "servers": [
    {
      "url": "https://insight.quizzman.com/api/tool-module/calendar",
      "description": "Production lab"
    }
  ],
  "tags": [
    { "name": "core", "description": "Solar/lunar conversion" },
    { "name": "astro", "description": "Astronomy / verification tools" },
    { "name": "meta", "description": "Health and discovery" }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["meta"],
        "summary": "Calendar module health",
        "operationId": "calendarHealth",
        "responses": {
          "200": {
            "description": "Module OK",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/today": {
      "get": {
        "tags": ["core"],
        "summary": "Today's solar/lunar / Can Chi for a region",
        "operationId": "calendarToday",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "schema": { "type": "string", "enum": ["VN", "CN"], "default": "VN" }
          }
        ],
        "responses": {
          "200": { "description": "Today payload" }
        }
      }
    },
    "/almanac": {
      "get": {
        "tags": ["core"],
        "summary": "Full day almanac pack for writing (Hoàng lịch)",
        "operationId": "calendarAlmanac",
        "parameters": [
          { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD; omit for today" },
          { "name": "timezone", "in": "query", "schema": { "type": "string", "enum": ["VN", "CN"], "default": "VN" } },
          { "name": "language", "in": "query", "schema": { "type": "string", "enum": ["vi", "en", "zh", "zht"], "default": "vi" } }
        ],
        "responses": {
          "200": { "description": "qm.calendar.almanac.v1 pack" }
        }
      },
      "post": {
        "tags": ["core"],
        "summary": "Full day almanac pack for writing",
        "operationId": "calendarAlmanacPost",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "date": { "type": "string", "format": "date" },
                  "day": { "type": "integer" },
                  "month": { "type": "integer" },
                  "year": { "type": "integer" },
                  "timezone": { "type": "string" },
                  "language": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "qm.calendar.almanac.v1 pack" }
        }
      }
    },
    "/almanac/schema": {
      "get": {
        "tags": ["meta"],
        "summary": "JSON Schema for the almanac pack",
        "operationId": "calendarAlmanacSchema",
        "responses": {
          "200": { "description": "JSON Schema qm.calendar.almanac.v1" }
        }
      }
    },
    "/solar-to-lunar": {
      "post": {
        "tags": ["core"],
        "summary": "Convert solar date to lunar",
        "operationId": "solarToLunar",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "year": { "type": "integer" },
                  "month": { "type": "integer" },
                  "day": { "type": "integer" },
                  "region": { "type": "string", "enum": ["VN", "CN"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Lunar date + Can Chi + solar terms" }
        }
      }
    },
    "/lunar-to-solar": {
      "post": {
        "tags": ["core"],
        "summary": "Convert lunar date to solar",
        "operationId": "lunarToSolar",
        "responses": {
          "200": { "description": "Solar date" }
        }
      }
    },
    "/astro/day-sky": {
      "get": {
        "tags": ["astro"],
        "summary": "Day-sky snapshot for Sky Viewer (λ☉, solar term, moon phase teaching model)",
        "operationId": "daySky",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "schema": { "type": "string", "format": "date", "example": "2024-11-03" }
          },
          {
            "name": "timezone",
            "in": "query",
            "schema": { "type": "string", "enum": ["VN", "CN"], "default": "VN" }
          }
        ],
        "responses": {
          "200": { "description": "Sky / solar-term payload (use solarTerm.current)" }
        }
      }
    },
    "/astro/true-solar-time": {
      "get": {
        "tags": ["astro"],
        "summary": "True Solar Time + hour Chi at longitude",
        "operationId": "trueSolarTimeGet",
        "parameters": [
          { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "time", "in": "query", "required": true, "schema": { "type": "string", "example": "12:45" } },
          { "name": "longitude", "in": "query", "required": true, "schema": { "type": "number", "example": 106.7 } },
          { "name": "timezone", "in": "query", "schema": { "type": "string", "example": "Asia/Ho_Chi_Minh" } }
        ],
        "responses": {
          "200": { "description": "True solar clock + Can Chi hour" }
        }
      }
    },
    "/astro/nasa-parity": {
      "get": {
        "tags": ["astro"],
        "summary": "Self-check VSOP87 λ☉ and New Moon vs NASA/USNO sample points",
        "operationId": "nasaParity",
        "responses": {
          "200": { "description": "Parity table (equinoxes/solstices + new moon deltas)" }
        }
      }
    },
    "/astro/tet-divergence": {
      "get": {
        "tags": ["astro"],
        "summary": "Scan years where Vietnam and China Tết (or month start) diverge",
        "operationId": "tetDivergence",
        "parameters": [
          { "name": "from", "in": "query", "schema": { "type": "integer", "example": 1960 } },
          { "name": "to", "in": "query", "schema": { "type": "integer", "example": 2040 } },
          { "name": "year", "in": "query", "schema": { "type": "integer", "description": "Single year shortcut" } }
        ],
        "responses": {
          "200": { "description": "List of divergence years / reasons" }
        }
      }
    }
  },
  "externalDocs": {
    "description": "About Quizzman Calendar (algorithms, applications, test cases)",
    "url": "https://insight.quizzman.com/tool/about-calendar"
  }
}
