openapi: 3.1.0
info:
  title: Verified Supplement Data — Recommendation API
  description: >-
    Free, no-auth, CORS-open JSON API for evidence-based dietary supplement
    guidance. Returns ranked product recommendations by cost-per-effective-dose,
    clinical dosing, and the supporting clinical evidence (with a PubMed PMID on
    every claim). Data from NIH DSLD, PubMed, NSF, and USP. Machine-readable
    layer of the open CC-BY-4.0 Verified Supplement Evidence Database
    (DOI 10.57967/hf/9356).
  version: "1.0"
  contact:
    name: Verified Supplement Data
    url: https://verifiedsupplementdata.com
    email: hello@verifiedsupplementdata.com
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  termsOfService: https://verifiedsupplementdata.com/about/
servers:
  - url: https://verifiedsupplementdata.com/api/v1
    description: Production
externalDocs:
  description: Methodology and dataset
  url: https://verifiedsupplementdata.com/methodology/
paths:
  /recommend/index.json:
    get:
      operationId: getIndex
      summary: List all supplements, their conditions, and product counts
      description: >-
        Self-documenting index of every supplement and the conditions available
        for it, plus the URL patterns for the recommendation and interaction
        endpoints.
      responses:
        "200":
          description: API index
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
                  version:
                    type: string
                  usage:
                    type: object
                  supplements:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        conditions:
                          type: array
                          items:
                            type: string
                        productCount:
                          type: integer
  /recommend/{supplement}/{condition}.json:
    get:
      operationId: getRecommendation
      summary: Ranked recommendation for a supplement + condition
      description: >-
        Returns the clinical dose, an evidence summary with a PubMed PMID, and a
        list of products ranked by cost-per-effective-daily-dose. Use the
        condition `all` to get every product for the supplement without a
        condition filter.
      parameters:
        - name: supplement
          in: path
          required: true
          description: Supplement id (e.g. magnesium, vitamin-d, omega-3, iron)
          schema:
            type: string
          example: magnesium
        - name: condition
          in: path
          required: true
          description: Condition id (e.g. sleep, anxiety) or `all`
          schema:
            type: string
          example: sleep
      responses:
        "200":
          description: Recommendation with evidence and ranked products
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Recommendation"
        "404":
          description: Unknown supplement or condition
  /recommend/interactions.json:
    get:
      operationId: getInteractions
      summary: Medication–nutrient depletion interactions
      description: >-
        Which medications deplete which nutrients (statins, metformin, PPIs,
        birth control, and more), with supporting references.
      responses:
        "200":
          description: Interaction records
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    Recommendation:
      type: object
      properties:
        supplement:
          type: string
        supplement_id:
          type: string
        condition:
          type: string
        condition_id:
          type: string
        recommendation:
          type: object
          properties:
            summary:
              type: string
            dose:
              type: string
            evidence:
              type: object
              properties:
                summary:
                  type: string
                level:
                  type: string
                pmid:
                  type: string
                pubmed_url:
                  type: string
                  format: uri
            source_page:
              type: string
              format: uri
        products:
          type: array
          items:
            $ref: "#/components/schemas/Product"
    Product:
      type: object
      properties:
        rank:
          type: integer
        name:
          type: string
        brand:
          type: string
        slug:
          type: string
        dose_per_serving:
          type: string
        serving_size:
          type: string
        servings_per_container:
          type: integer
        price_usd:
          type: number
        cost_per_effective_daily_dose_usd:
          type: number
        certification:
          type: string
        editorial_pick:
          type: string
        nih_dsld_id:
          type: string
        buy_url:
          type: string
          format: uri