{
  "openapi": "3.0.3",
  "info": {
    "title": "Sync My Cycle",
    "version": "1.0.0",
    "description": "Tells the user which phase of their menstrual cycle they are probably in today (menstrual, follicular, ovulatory or luteal), with workout and food ideas that suit it, and a look at the week ahead. Uses only the dates the user gives in the conversation. Nothing is stored or logged, and there is no account. Every answer has a ready-to-read `say` line and a `note` that must be respected: general wellbeing guidance only, not medical advice, and never for planning or avoiding pregnancy.",
    "contact": { "email": "hello@askmizan.com" }
  },
  "servers": [{ "url": "https://syncmycycle.pages.dev" }],
  "paths": {
    "/v1/today": {
      "get": {
        "operationId": "getTodaysPhase",
        "summary": "Today's cycle phase, with workout and food ideas",
        "description": "Use when the user asks what phase they are in, what workout or food suits them today, or why their energy is up or down. Needs the first day of their last period. Ask for it if they have not given it; never guess it.",
        "parameters": [
          { "name": "last_period", "in": "query", "required": true, "description": "First day of the user's most recent period, YYYY-MM-DD. Must be within the last 120 days.", "schema": { "type": "string", "format": "date" } },
          { "name": "cycle_length", "in": "query", "required": false, "description": "Usual days from one period start to the next, 20 to 45. Default 28.", "schema": { "type": "integer", "minimum": 20, "maximum": 45 } },
          { "name": "period_length", "in": "query", "required": false, "description": "Usual days of bleeding, 2 to 10. Default 5.", "schema": { "type": "integer", "minimum": 2, "maximum": 10 } },
          { "name": "date", "in": "query", "required": false, "description": "Day to ask about, YYYY-MM-DD. Default today (UTC).", "schema": { "type": "string", "format": "date" } },
          { "name": "diet", "in": "query", "required": false, "description": "Comma separated: vegetarian, vegan, pescatarian, halal. Food ideas are filtered to suit.", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Today's phase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Today" } } } }, "400": { "description": "Missing or unusable dates, with a message saying what to ask the user" } }
      }
    },
    "/v1/week": {
      "get": {
        "operationId": "getWeekAhead",
        "summary": "The days ahead by phase",
        "description": "Use when the user wants to plan training or meals for the week. Returns each day's likely phase, workout focus, intensity and food focus.",
        "parameters": [
          { "name": "last_period", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "cycle_length", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 20, "maximum": 45 } },
          { "name": "period_length", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2, "maximum": 10 } },
          { "name": "date", "in": "query", "required": false, "description": "First day of the plan, YYYY-MM-DD. Default today.", "schema": { "type": "string", "format": "date" } },
          { "name": "days", "in": "query", "required": false, "description": "How many days, 1 to 35. Default 7.", "schema": { "type": "integer", "minimum": 1, "maximum": 35 } }
        ],
        "responses": { "200": { "description": "Days ahead" }, "400": { "description": "Missing or unusable dates" } }
      }
    },
    "/v1/phases": { "get": { "operationId": "listPhases", "summary": "What each phase usually feels like, with workout and food ideas", "description": "Use for general questions about cycle syncing that need no dates.", "responses": { "200": { "description": "The four phase guides" } } } },
    "/v1/health": { "get": { "operationId": "health", "summary": "Service status", "responses": { "200": { "description": "OK" } } } }
  },
  "components": {
    "schemas": {
      "Today": {
        "type": "object",
        "properties": {
          "say": { "type": "string", "description": "A short answer to read to the user." },
          "date": { "type": "string" },
          "day_of_cycle": { "type": "integer" },
          "phase": { "type": "string", "enum": ["menstrual", "follicular", "ovulatory", "luteal"] },
          "phase_name": { "type": "string" },
          "energy": { "type": "string" },
          "workout": { "type": "object", "properties": { "focus": { "type": "string" }, "intensity": { "type": "string" }, "ideas": { "type": "array", "items": { "type": "string" } } } },
          "food": { "type": "object", "properties": { "focus": { "type": "string" }, "nutrients": { "type": "array", "items": { "type": "string" } }, "ideas": { "type": "array", "items": { "type": "string" } } } },
          "self_care": { "type": "array", "items": { "type": "string" } },
          "next_phase": { "type": "object", "properties": { "phase": { "type": "string" }, "name": { "type": "string" }, "starts_in_days": { "type": "integer" }, "starts_on": { "type": "string" } } },
          "next_period_estimate": { "type": "string" },
          "assumed_regular": { "type": "string", "nullable": true },
          "note": { "type": "string", "description": "Always pass this caution on when relevant." }
        }
      }
    }
  }
}