{
  "openapi": "3.1.0",
  "info": {
    "title": "BabyData Baby and Pregnancy Tools API",
    "summary": "Read-only UK baby-and-pregnancy calculators that show their working.",
    "description": "Machine-readable access to the BabyData calculators: due date (Naegele's rule), ovulation and fertile window, pregnancy weeks, and UK Statutory Maternity Pay. Each response returns the rule it used and a primary UK source. Pregnancy outputs are informational only, not medical advice, and are editorially reviewed against NHS and gov.uk guidance. Read-only, no authentication, no PII, CC BY 4.0. Also exposed as an MCP server at /mcp (see /.well-known/mcp.json).",
    "version": "2026-06-12",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "BabyData",
      "url": "https://example.namenest.placeholder/api/"
    }
  },
  "servers": [
    { "url": "https://example.namenest.placeholder", "description": "Placeholder; set the real domain at launch" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://example.namenest.placeholder/api/"
  },
  "paths": {
    "/api/due-date": {
      "get": {
        "operationId": "calculateDueDate",
        "summary": "Estimate a due date and current pregnancy stage",
        "description": "Uses Naegele's rule. Provide a dating method and the relevant date. Returns the estimated due date, weeks pregnant now, trimester and weeks remaining. Informational only, not medical advice.",
        "parameters": [
          { "name": "method", "in": "query", "required": false, "description": "Dating method (default lmp).", "schema": { "type": "string", "enum": ["lmp", "conception", "ivf"] } },
          { "name": "date", "in": "query", "required": true, "description": "The relevant date: LMP, conception, or IVF transfer date.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-15" },
          { "name": "embryoAge", "in": "query", "required": false, "description": "Embryo age in days at IVF transfer (commonly 3 or 5; default 5).", "schema": { "type": "integer", "minimum": 0, "maximum": 7 } },
          { "name": "asOf", "in": "query", "required": false, "description": "Reference date for weeks-pregnant-now (default today).", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": { "description": "Due-date estimate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DueDate" } } } },
          "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/ovulation": {
      "get": {
        "operationId": "calculateOvulation",
        "summary": "Estimate ovulation day and the fertile window",
        "description": "Ovulation day = cycle length minus 14; fertile window = ovulation day plus the 5 days before it. Informational only.",
        "parameters": [
          { "name": "lastPeriod", "in": "query", "required": true, "description": "First day of last period.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-15" },
          { "name": "cycleLength", "in": "query", "required": false, "description": "Average cycle length in days (default 28).", "schema": { "type": "integer", "minimum": 20, "maximum": 45 } }
        ],
        "responses": {
          "200": { "description": "Ovulation estimate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ovulation" } } } },
          "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/pregnancy-weeks": {
      "get": {
        "operationId": "pregnancyWeeks",
        "summary": "How many weeks pregnant, with trimester and progress",
        "description": "Counts weeks plus days from the LMP, or from a due date (LMP worked back as dueDate minus 280 days). Informational only, not medical advice.",
        "parameters": [
          { "name": "lmp", "in": "query", "required": false, "description": "First day of last period.", "schema": { "type": "string", "format": "date" } },
          { "name": "dueDate", "in": "query", "required": false, "description": "Due date (alternative to lmp).", "schema": { "type": "string", "format": "date" } },
          { "name": "asOf", "in": "query", "required": false, "description": "Reference date (default today).", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": { "description": "Pregnancy-weeks result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PregnancyWeeks" } } } },
          "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/maternity-pay": {
      "get": {
        "operationId": "maternityPay",
        "summary": "Estimate UK Statutory Maternity Pay over 39 weeks",
        "description": "gov.uk rule: 6 weeks at 90% of average weekly earnings, then 33 weeks at the lower of the statutory flat rate or 90%. The flat rate is a placeholder to confirm on gov.uk at launch. Estimate only, before tax, excludes enhanced employer schemes.",
        "parameters": [
          { "name": "weeklyEarnings", "in": "query", "required": false, "description": "Average weekly earnings before tax (GBP).", "schema": { "type": "number" } },
          { "name": "annualSalary", "in": "query", "required": false, "description": "Annual salary before tax (GBP), converted at /52.", "schema": { "type": "number" } }
        ],
        "responses": {
          "200": { "description": "Maternity-pay estimate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaternityPay" } } } },
          "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DueDate": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "method": { "type": "string", "enum": ["lmp", "conception", "ivf"] },
          "effective_lmp": { "type": "string", "format": "date" },
          "due_date": { "type": "string", "format": "date" },
          "gestation_days_at_term": { "type": "integer" },
          "weeks_pregnant_now": { "type": ["integer", "null"] },
          "days_into_week_now": { "type": ["integer", "null"] },
          "trimester_now": { "type": ["string", "null"] },
          "weeks_remaining": { "type": ["integer", "null"] },
          "as_of": { "type": "string", "format": "date" },
          "rule": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      },
      "Ovulation": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "last_period": { "type": "string", "format": "date" },
          "cycle_length": { "type": "integer" },
          "ovulation_date": { "type": "string", "format": "date" },
          "fertile_window_start": { "type": "string", "format": "date" },
          "fertile_window_end": { "type": "string", "format": "date" },
          "next_period": { "type": "string", "format": "date" },
          "rule": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      },
      "PregnancyWeeks": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "effective_lmp": { "type": "string", "format": "date" },
          "as_of": { "type": "string", "format": "date" },
          "weeks": { "type": "integer" },
          "days": { "type": "integer" },
          "trimester": { "type": "string" },
          "percent_through": { "type": "integer" },
          "weeks_remaining": { "type": "integer" },
          "rule": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      },
      "MaternityPay": {
        "type": "object",
        "properties": {
          "schema_version": { "type": "string" },
          "source": { "type": "string", "format": "uri" },
          "license": { "type": "string", "format": "uri" },
          "average_weekly_earnings": { "type": "number" },
          "weeks_1_to_6_weekly": { "type": "number" },
          "weeks_7_to_39_weekly": { "type": "number" },
          "estimated_total_39_weeks": { "type": "number" },
          "flat_rate_used": { "type": "number" },
          "flat_rate_status": { "type": "string" },
          "currency": { "type": "string", "enum": ["GBP"] },
          "rule": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}