{
  "openapi": "3.1.0",
  "info": {
    "title": "Her Vitals Data API",
    "summary": "Read-only public data on UK women's life-stage supplement categories.",
    "description": "Machine-readable access to Her Vitals's editorial index of supplement categories for UK women across life stages (trying to conceive, pregnancy, postnatal, perimenopause, menopause, senior). Each category carries the EFSA-permitted 'contributes to normal ...' roles, the 'what to look for when buying' points and the real named UK brand placeholders featured on its pillar page. INFORMATION ONLY, NOT MEDICAL ADVICE: supplements are regulated as food, not medicines, and cannot legally claim to treat any condition. 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": "Her Vitals",
      "url": "https://hervitals.co.uk/api/"
    }
  },
  "servers": [
    { "url": "https://hervitals.co.uk", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://hervitals.co.uk/api/"
  },
  "paths": {
    "/api/supplements": {
      "get": {
        "operationId": "listSupplements",
        "summary": "List the supplement categories Her Vitals covers",
        "description": "Returns all tracked supplement categories, or a filtered subset when a query is supplied. Every response carries a disclaimer: information only, not medical advice.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text match on nutrient name, EFSA roles, buying points and brand placeholders.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of supplement categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "count": { "type": "integer" },
                    "supplements": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Supplement" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/supplements/{slug}": {
      "get": {
        "operationId": "getSupplement",
        "summary": "Get a single supplement category by slug",
        "description": "Accepts the canonical slug (e.g. magnesium, vitamin-d, creatine-for-women).",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "magnesium"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching supplement category.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "supplement": { "$ref": "#/components/schemas/Supplement" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No supplement category matches the slug.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/life-stages": {
      "get": {
        "operationId": "getLifeStages",
        "summary": "List the women's life stages Her Vitals organises content around",
        "description": "Trying to conceive, pregnancy, postnatal, perimenopause, menopause and the senior years, each with its on-site hub URL.",
        "responses": {
          "200": {
            "description": "Life-stage index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "source": { "type": "string", "format": "uri" },
                    "license": { "type": "string", "format": "uri" },
                    "disclaimer": { "type": "string" },
                    "count": { "type": "integer" },
                    "life_stages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string" },
                          "label": { "type": "string" },
                          "url": { "type": "string", "format": "uri" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Brand": {
        "type": "object",
        "description": "A real named UK product placeholder. Links are wired post-launch; no fabricated URLs.",
        "properties": {
          "brand": { "type": "string" },
          "product": { "type": "string" },
          "retailer": { "type": "string" },
          "form": { "type": "string" },
          "suits": { "type": "string" },
          "note": { "type": "string" }
        },
        "required": ["brand", "form"]
      },
      "Supplement": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "efsa_roles": {
            "type": "array",
            "description": "EFSA-permitted 'contributes to normal ...' role fragments. Factual, not therapeutic claims.",
            "items": { "type": "string" }
          },
          "buying_points": {
            "type": "array",
            "items": { "type": "string" }
          },
          "brands": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Brand" }
          },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["slug", "name", "efsa_roles", "url"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}