{
  "openapi": "3.1.0",
  "info": {
    "title": "Ovuloom Fertility & Cycle Intelligence API",
    "description": "Official Ovuloom API for ChatGPT Actions and AI Assistants. Provides free evidence-based ovulation & fertility window calculations, reproductive symptom screening (PCOS, Endometriosis, Luteal Phase), and OAuth-authenticated subscriber tools for syncing personal cycle history, logging daily BBT/LH/symptoms, and generating 90-day OB-GYN/REI clinician reports.",
    "version": "1.0.0",
    "contact": {
      "name": "Ovuloom Support (MannaSync Solutions Inc.)",
      "url": "https://www.ovuloom.com/contact",
      "email": "contact@ovuloom.com"
    },
    "termsOfService": "https://www.ovuloom.com/terms-of-service"
  },
  "servers": [
    {
      "url": "https://www.ovuloom.com",
      "description": "Ovuloom Production API"
    }
  ],
  "components": {
    "securitySchemes": {
      "OvuloomOAuth": {
        "type": "oauth2",
        "description": "Sign in with your Ovuloom account to unlock subscriber cycle syncing, daily BBT/symptom logging, and clinician reports.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://www.ovuloom.com/oauth/authorize",
            "tokenUrl": "https://www.ovuloom.com/oauth/token",
            "scopes": {
              "cycle:read": "Read your Ovuloom subscription tier, cycle predictions, and recent daily logs.",
              "cycle:write": "Log daily BBT, menstrual flow, ovulation test results, and symptoms to your Ovuloom account."
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/calculate-fertility-window": {
      "post": {
        "operationId": "calculateFertilityWindow",
        "summary": "Calculate ovulation date, 6-day fertile window, peak fertility days, and next period date (Free).",
        "description": "Stateless clinical fertility window calculator using luteal phase back-calculation. Supports regular and irregular cycle lengths (20-45 days). Free for all users.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["lastPeriodDate"],
                "properties": {
                  "lastPeriodDate": {
                    "type": "string",
                    "description": "First day of the last menstrual period in YYYY-MM-DD format."
                  },
                  "averageCycleLength": {
                    "type": "integer",
                    "default": 28,
                    "minimum": 20,
                    "maximum": 45,
                    "description": "Average cycle length in days (default 28)."
                  },
                  "lutealPhaseLength": {
                    "type": "integer",
                    "default": 14,
                    "minimum": 10,
                    "maximum": 16,
                    "description": "Average luteal phase length in days (default 14)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculated ovulation date, fertile window, peak days, and current cycle phase."
          }
        }
      }
    },
    "/api/v1/screen-reproductive-risk": {
      "post": {
        "operationId": "screenReproductiveSymptoms",
        "summary": "Screen cycle patterns and symptoms for PCOS, Endometriosis, or Luteal Phase considerations (Free).",
        "description": "Evaluates cycle regularity, pelvic pain severity, and reported symptoms to provide educational reproductive health insights and clinician discussion questions.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "averageCycleLength": {
                    "type": "integer",
                    "description": "Average cycle length in days."
                  },
                  "cycleVariabilityDays": {
                    "type": "integer",
                    "description": "Day-to-day variation between cycles."
                  },
                  "pelvicPainSeverity": {
                    "type": "string",
                    "enum": ["none", "mild", "moderate", "severe"],
                    "description": "Severity of menstrual or pelvic pain."
                  },
                  "symptoms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Reported symptoms (e.g., spotting, severe cramps, acne, hirsutism, irregular ovulation)."
                  },
                  "tryingToConceiveMonths": {
                    "type": "integer",
                    "description": "Months actively trying to conceive."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Educational pattern screening and recommended OB-GYN / REI questions."
          }
        }
      }
    },
    "/api/v1/cycle-summary": {
      "get": {
        "operationId": "getSubscriberCycleSummary",
        "summary": "Get the authenticated Ovuloom subscriber's personal cycle history, fertile window, and recent BBT/symptom logs.",
        "description": "Requires an active Ovuloom Premium, Pro, or Family subscription. Returns the user's synced cycle predictions, BBT summary, and last 14 days of daily logs.",
        "security": [
          {
            "OvuloomOAuth": ["cycle:read"]
          }
        ],
        "responses": {
          "200": {
            "description": "Subscriber cycle summary or upgrade prompt if on the free tier."
          }
        }
      }
    },
    "/api/v1/daily-log": {
      "post": {
        "operationId": "saveSubscriberDailyLog",
        "summary": "Log daily BBT, menstrual flow, cervical mucus, OPK result, mood, pain, and notes to the subscriber's Ovuloom account.",
        "description": "Requires an active Ovuloom Premium, Pro, or Family subscription. Syncs directly with the Ovuloom iOS, Android, and Web app.",
        "security": [
          {
            "OvuloomOAuth": ["cycle:write"]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": "string",
                    "description": "Date in YYYY-MM-DD format (defaults to today)."
                  },
                  "temperature": {
                    "type": "number",
                    "description": "Basal body temperature (BBT) in °F or °C."
                  },
                  "weight": {
                    "type": "number",
                    "description": "Body weight."
                  },
                  "flow": {
                    "type": "string",
                    "enum": ["none", "spotting", "light", "medium", "heavy"],
                    "description": "Menstrual flow intensity."
                  },
                  "cervicalMucus": {
                    "type": "string",
                    "enum": ["dry", "sticky", "creamy", "watery", "egg_white"],
                    "description": "Cervical mucus quality."
                  },
                  "opkResult": {
                    "type": "string",
                    "enum": ["negative", "low", "high", "peak_positive"],
                    "description": "Ovulation Predictor Kit (LH surge) test result."
                  },
                  "mood": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Mood tags."
                  },
                  "pain": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Pain or physical symptom tags."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Free-text daily notes."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Confirmation of synced daily log entry."
          }
        }
      }
    },
    "/api/v1/clinician-report": {
      "get": {
        "operationId": "generateClinicianReport",
        "summary": "Generate a 90-day clinical fertility & cycle summary for an OB-GYN or REI consultation.",
        "description": "Aggregates 90 days of cycle lengths, BBT readings, and symptom frequencies for the authenticated Ovuloom subscriber.",
        "security": [
          {
            "OvuloomOAuth": ["cycle:read"]
          }
        ],
        "responses": {
          "200": {
            "description": "90-day structured clinician summary."
          }
        }
      }
    }
  }
}