{"openapi":"3.1.0","info":{"title":"Dietary Supplement Label and Nutrient Intake Analysis","version":"0.15.1","description":"Look up dietary supplement labels from the NIH Dietary Supplement Label Database (DSLD) and total vitamin and mineral intake across a list of supplements, compared with NIH recommended amounts (RDA/AI) and upper limits (UL). Information only, not medical advice; see the terms of use: https://github.com/chariot-ventures/dietary-supplement-analysis/blob/main/TERMS.md"},"externalDocs":{"url":"https://github.com/chariot-ventures/dietary-supplement-analysis#readme"},"servers":[{"url":"/"}],"paths":{"/":{"get":{"summary":"Service identity","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/version":{"get":{"summary":"Identity probe","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"const":"dietary-supplement-analysis"},"version":{"type":"string"}},"required":["service","version"]}}}}}}},"/v1/health":{"get":{"summary":"Readiness","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"ok"}}}}}}}}},"/v1/products/search":{"post":{"summary":"Search DSLD products","description":"Searches the NIH DSLD and returns up to `limit` (max 10) product summaries. On-market only by default.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"description":"Free-text search, e.g. \"vitamin d3 5000\"","type":"string","minLength":1,"maxLength":200},"brand":{"type":"string","minLength":1,"maxLength":100},"ingredient":{"description":"Ingredient name, e.g. \"cholecalciferol\"","type":"string","minLength":1,"maxLength":100},"on_market_only":{"default":true,"type":"boolean"},"limit":{"default":5,"type":"integer","minimum":1,"maximum":10},"dedupe_versions":{"default":true,"description":"Collapse label versions of the same product (same brand and name) into one result, newest first; older IDs are listed in other_versions","type":"boolean"}}},"examples":{"by_name":{"value":{"query":"vitamin d3 5000","limit":3}},"by_brand_and_ingredient":{"value":{"brand":"Thorne","ingredient":"magnesium"}}}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","const":"dietary-supplement-analysis"},"version":{"type":"string"},"as_of":{"type":"string","format":"date"},"query":{"type":"object"},"total_hits":{"type":"integer"},"returned":{"type":"integer"},"search_source":{"type":"string","enum":["dsld","local"],"description":"\"local\" when NIH DSLD was unreachable and results came from the service's own label store"},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/lookup":{"post":{"summary":"Look up a product by barcode","description":"The DSLD label whose UPC matches, newest version first. Spaces and dashes in the barcode are ignored; a 13-digit EAN with a leading 0 matches its 12-digit UPC.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upc":{"type":"string","minLength":8,"maxLength":32,"description":"UPC-A or EAN barcode digits as printed on the bottle, e.g. \"031604026974\" (spaces and dashes are ignored)"}},"required":["upc"],"additionalProperties":false},"examples":{"upc":{"value":{"upc":"031604026974"}}}}}},"responses":{"200":{"description":"Label for the barcode","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","const":"dietary-supplement-analysis"},"version":{"type":"string"},"as_of":{"type":"string","format":"date"},"upc":{"type":"string"},"dsld_id":{"type":"integer"},"other_versions":{"type":"array","items":{"type":"object","properties":{"dsld_id":{"type":"integer"},"entry_date":{"type":["string","null"]},"on_market":{"type":["boolean","null"]}}}},"product":{"$ref":"#/components/schemas/Label"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/fda":{"post":{"summary":"FDA recalls and adverse event reports","description":"Recalls (openFDA food enforcement reports, which cover dietary supplements) and CAERS adverse event reports for one product, given as a DSLD ID, barcode, name, or brand and name. A recall is listed only when its description carries the product's barcode or the brand and every distinctive product-name word; others mentioning the brand are counted. Adverse event reports are counted for the product (brand and name words) or, failing that, the brand. A report does not show that the product caused the event.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dsld_id":{"type":"integer","exclusiveMinimum":0,"maximum":10000000,"description":"DSLD label ID, e.g. from /v1/products/search"},"upc":{"type":"string","minLength":8,"maxLength":32,"description":"UPC-A or EAN barcode digits as printed on the bottle, e.g. \"031604026974\" (spaces and dashes are ignored)"},"query":{"description":"Product as the user named it; resolved to a DSLD label","type":"string","minLength":2,"maxLength":200},"brand":{"description":"Brand (with \"name\", or to narrow \"query\")","type":"string","minLength":2,"maxLength":100},"name":{"description":"Product name as printed, used with \"brand\" when the product is not in DSLD","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"examples":{"by_name":{"value":{"query":"Nature Made Vitamin D3 1000 IU"}},"by_brand":{"value":{"brand":"Nature Made","name":"D3 1000 IU"}},"by_barcode":{"value":{"upc":"031604026974"}}}}}},"responses":{"200":{"description":"FDA records","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","const":"dietary-supplement-analysis"},"version":{"type":"string"},"as_of":{"type":"string","format":"date"},"product":{"type":"object","properties":{"dsld_id":{"type":["integer","null"]},"brand":{"type":"string"},"name":{"type":"string"},"upc":{"type":["string","null"]}}},"agent_summary":{"type":"string"},"recalls":{"type":"object","properties":{"matched":{"type":"array","items":{"type":"object","properties":{"recall_number":{"type":"string"},"classification":{"type":["string","null"]},"status":{"type":["string","null"]},"reason_for_recall":{"type":["string","null"]},"product_description":{"type":"string"},"recalling_firm":{"type":["string","null"]},"recall_initiation_date":{"type":["string","null"]},"report_date":{"type":["string","null"]},"matched_by":{"type":"string","enum":["upc","brand_and_name"]}}}},"brand_recalls_total":{"type":"integer"},"last_updated":{"type":["string","null"]},"search_url":{"type":"string"}}},"adverse_events":{"type":"object","properties":{"scope":{"type":"string","enum":["product","brand","none"]},"total":{"type":"integer"},"top_reactions":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"count":{"type":"integer"}}}},"last_updated":{"type":["string","null"]},"search_url":{"type":"string"},"note":{"type":"string"}}},"data_gaps":{"type":"array","items":{"$ref":"#/components/schemas/DataGap"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/get":{"post":{"summary":"Get normalized labels","description":"Normalized label(s) by DSLD ID (max 10). Original label amounts are kept next to converted amounts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dsld_id":{"type":"integer","exclusiveMinimum":0,"maximum":10000000,"description":"DSLD label ID, e.g. from /v1/products/search"},"dsld_ids":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":10000000,"description":"DSLD label ID, e.g. from /v1/products/search"}}}}}}},"responses":{"200":{"description":"Labels","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","const":"dietary-supplement-analysis"},"version":{"type":"string"},"as_of":{"type":"string","format":"date"},"requested":{"type":"integer"},"returned":{"type":"integer"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Label"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/nutrients/reference":{"post":{"summary":"Reference intakes for a nutrient","description":"RDA, EAR, AI and UL for one nutrient at an age and sex. Offline and deterministic.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nutrient":{"type":"string","minLength":1,"maxLength":100,"description":"Nutrient ID (\"vitamin-d\") or any synonym (\"cholecalciferol\")"},"age":{"type":"number","minimum":0,"maximum":120,"description":"Age in years. For infants use a fraction: 0.25 = 3 months; 0-5 and 6-11 month values apply under 1."},"sex":{"type":"string","enum":["male","female"]},"life_stage":{"type":"string","enum":["pregnancy","lactation"],"description":"Pregnancy or lactation (breastfeeding) reference values; requires sex \"female\" and age 14-50"}},"required":["nutrient","age","sex"]},"examples":{"vitamin_d":{"value":{"nutrient":"vitamin d","age":34,"sex":"female"}},"zinc":{"value":{"nutrient":"zinc","age":6,"sex":"male"}}}}}},"responses":{"200":{"description":"Reference values","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","const":"dietary-supplement-analysis"},"version":{"type":"string"},"as_of":{"type":"string","format":"date"},"nutrient":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"unit":{"type":"string"}}},"profile":{"type":"object","properties":{"age":{"type":"number"},"sex":{"type":"string"}}},"reference":{"$ref":"#/components/schemas/Reference"},"has_dri":{"type":"boolean"},"factsheet_url":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stack/analyze":{"post":{"summary":"Analyze a supplement stack","description":"Per-nutrient daily totals across 1-15 products (product names, barcodes, DSLD IDs or custom ingredient lists), compared with upper limits and reference intakes when age and sex are given. Returns a plain-language agent_summary, how each named product was identified, single-product changes that would bring above-UL nutrients under the UL, and (with candidates) the effect of adding each candidate. No flag means nothing to report, not a judgement about the stack.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"age":{"type":"number","minimum":0,"maximum":120,"description":"Age in years. For infants use a fraction: 0.25 = 3 months; 0-5 and 6-11 month values apply under 1."},"sex":{"type":"string","enum":["male","female"]},"life_stage":{"type":"string","enum":["pregnancy","lactation"],"description":"Pregnancy or lactation (breastfeeding) reference values; requires sex \"female\" and age 14-50"},"detail":{"default":"full","description":"\"summary\" returns only what an agent needs to answer (agent_summary, flagged nutrients, suggestions, resolutions, candidate verdicts), about 1-3 KB instead of 20-40 KB","type":"string","enum":["summary","full"]},"lang":{"default":"en","description":"\"es\" writes agent_summary in Spanish (the English text is kept in agent_summary_en); other fields stay in English","type":"string","enum":["en","es"]},"diet":{"default":"none","description":"\"typical\" adds the US average intake from food and drinks for this age and sex (NHANES) to estimate total intake; see with_typical_diet","type":"string","enum":["none","typical"]},"products":{"minItems":1,"maxItems":15,"type":"array","items":{"anyOf":[{"type":"object","properties":{"dsld_id":{"type":"integer","exclusiveMinimum":0,"maximum":10000000,"description":"DSLD label ID, e.g. from /v1/products/search"},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."}},"required":["dsld_id"],"additionalProperties":false},{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":200,"description":"Product as the user named it, e.g. \"Centrum Silver Women 50+\". Resolved to the best-matching DSLD label; see resolutions[]"},"brand":{"description":"Brand, if known separately","type":"string","minLength":1,"maxLength":100},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."}},"required":["query"],"additionalProperties":false},{"type":"object","properties":{"upc":{"type":"string","minLength":8,"maxLength":32,"description":"UPC-A or EAN barcode digits as printed on the bottle, e.g. \"031604026974\" (spaces and dashes are ignored)"},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."}},"required":["upc"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."},"ingredients":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"amount":{"type":"number","minimum":0,"maximum":10000000},"unit":{"type":"string","minLength":1,"maxLength":30,"description":"mg, mcg, g, IU, mcg DFE, mcg RAE, mg NE"},"form":{"description":"Declared form, e.g. \"folic acid\", \"retinyl palmitate\", \"d-alpha tocopherol\"","type":"string","minLength":1,"maxLength":200},"nutrient_basis":{"description":"For minerals: whether amount is elemental or the whole compound weight","type":"string","enum":["elemental","compound"]}},"required":["name","amount","unit"]}}},"required":["ingredients"],"additionalProperties":false}]},"description":"1-15 products. Each is one of: {\"dsld_id\"}, {\"query\"} (a product name, resolved server-side), {\"upc\"} (barcode), or a custom product {\"name\",\"ingredients\"}. Add \"servings_per_day\" to any of them."},"medications":{"minItems":1,"maxItems":30,"type":"array","items":{"type":"string","minLength":2,"maxLength":100},"description":"Medications the person takes, as generic or brand names (\"warfarin\", \"Synthroid\", \"metformin 500 mg\"). Checked against the medication interactions listed in the NIH ODS fact sheets; not exhaustive. Never logged."},"conditions":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["smoker","kidney_disease","hemochromatosis","lab_test_soon","cancer_treatment"]},"description":"Conditions that change how NIH reads a dose: smoker (current or former, or asbestos exposure: beta-carotene), kidney_disease (potassium, magnesium, phosphorus), hemochromatosis (iron, vitamin C), lab_test_soon (biotin interferes with lab tests), cancer_treatment (antioxidant doses)"},"foods":{"description":"Optional, up to 30: what the person eats in a day, e.g. [{\"query\":\"spinach cooked\",\"amount\":1,\"unit\":\"cup\"},{\"query\":\"whole milk\",\"grams\":488}]. Added to the supplement totals in nutrient_totals[].with_foods (USDA SR28, offline). Use instead of diet \"typical\".","minItems":1,"maxItems":30,"type":"array","items":{"type":"object","properties":{"query":{"description":"Food as the user named it, e.g. \"spinach cooked\", \"whole milk\"; matched to a USDA SR28 food (see foods.items)","type":"string","minLength":2,"maxLength":120},"ndb_number":{"description":"USDA NDB number (SR Legacy), e.g. \"11458\"","type":"string","pattern":"^\\d{4,5}$"},"grams":{"description":"Amount eaten per day, in grams","type":"number","exclusiveMinimum":0,"maximum":5000},"amount":{"description":"Amount in \"unit\" per day, e.g. 1.5 with unit \"cup\"","type":"number","exclusiveMinimum":0,"maximum":100},"unit":{"description":"cup, tbsp, tsp, slice, large, medium, oz, lb, kg, g, fl oz... must match a USDA portion for the food (or be a weight)","type":"string","minLength":1,"maxLength":30}},"additionalProperties":false}},"candidates":{"description":"Optional, up to 5: products the user is considering adding. Each is evaluated as an addition to the stack in candidate_results[]; they are not included in nutrient_totals.","minItems":1,"maxItems":5,"type":"array","items":{"anyOf":[{"type":"object","properties":{"dsld_id":{"type":"integer","exclusiveMinimum":0,"maximum":10000000,"description":"DSLD label ID, e.g. from /v1/products/search"},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."}},"required":["dsld_id"],"additionalProperties":false},{"type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":200,"description":"Product as the user named it, e.g. \"Centrum Silver Women 50+\". Resolved to the best-matching DSLD label; see resolutions[]"},"brand":{"description":"Brand, if known separately","type":"string","minLength":1,"maxLength":100},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."}},"required":["query"],"additionalProperties":false},{"type":"object","properties":{"upc":{"type":"string","minLength":8,"maxLength":32,"description":"UPC-A or EAN barcode digits as printed on the bottle, e.g. \"031604026974\" (spaces and dashes are ignored)"},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."}},"required":["upc"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"servings_per_day":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Servings taken per day. Default: the label maximum daily servings, else 1."},"ingredients":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"amount":{"type":"number","minimum":0,"maximum":10000000},"unit":{"type":"string","minLength":1,"maxLength":30,"description":"mg, mcg, g, IU, mcg DFE, mcg RAE, mg NE"},"form":{"description":"Declared form, e.g. \"folic acid\", \"retinyl palmitate\", \"d-alpha tocopherol\"","type":"string","minLength":1,"maxLength":200},"nutrient_basis":{"description":"For minerals: whether amount is elemental or the whole compound weight","type":"string","enum":["elemental","compound"]}},"required":["name","amount","unit"]}}},"required":["ingredients"],"additionalProperties":false}]}}},"required":["products"]},"examples":{"by_name":{"value":{"age":62,"sex":"female","products":[{"query":"Centrum Silver Women 50+"},{"query":"Thompson Zinc 50 mg","servings_per_day":1},{"upc":"031604026974"}]}},"what_if":{"value":{"age":34,"sex":"female","products":[{"dsld_id":338022}],"candidates":[{"query":"vitamin d3 5000 iu"}]}},"custom":{"value":{"age":6,"sex":"male","products":[{"name":"Immune gummy","ingredients":[{"name":"zinc","amount":10,"unit":"mg"}]}]}},"with_medications":{"value":{"age":58,"sex":"male","detail":"summary","medications":["warfarin","Synthroid"],"conditions":["smoker"],"products":[{"name":"Daily multi","ingredients":[{"name":"vitamin K","amount":120,"unit":"mcg"},{"name":"calcium","amount":500,"unit":"mg"}]}]}}}}}},"responses":{"200":{"description":"Stack analysis","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","const":"dietary-supplement-analysis"},"version":{"type":"string"},"as_of":{"type":"string","format":"date"},"profile":{"oneOf":[{"type":"object","properties":{"age":{"type":"number"},"sex":{"type":"string"}}},{"type":"null"}]},"summary":{"type":"object","properties":{"products_matched":{"type":"integer"},"nutrients_totaled":{"type":"integer"},"above_ul":{"type":"integer"},"near_ul":{"type":"integer"},"data_gaps":{"type":"integer"},"data_suspect":{"type":"integer"},"products_unresolved":{"type":"integer"},"suggestions":{"type":"integer"}}},"detail":{"type":"string","const":"summary","description":"Present only with \"detail\": \"summary\": the response then has profile, summary, agent_summary, resolutions, flagged, suggestions, candidate_results, data_gap_codes and provenance"},"agent_summary":{"type":"string","description":"Plain sentences summarizing the result, ready to relay as written; in Spanish with \"lang\": \"es\""},"lang":{"type":"string","const":"es","description":"Present with \"lang\": \"es\""},"agent_summary_en":{"type":"string","description":"With \"lang\": \"es\": the English agent_summary"},"flagged":{"type":"array","items":{"type":"object"},"description":"detail=summary only: flagged nutrients with amount, UL, percent, severity and UL basis"},"data_gap_codes":{"type":"array","items":{"type":"string"},"description":"detail=summary only"},"provenance":{"type":"object","properties":{"version":{"type":"string"},"commit":{"type":["string","null"]},"reference_values_reviewed":{"type":"string"}},"description":"Code version, git commit and reference-data review date behind this answer; full detail at GET /v1/provenance"},"resolutions":{"type":"array","items":{"$ref":"#/components/schemas/Resolution"},"description":"Present when any product was given as {query} or {upc}"},"assumptions":{"type":"array","items":{"type":"string"}},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/Suggestion"}},"candidate_results":{"type":"array","items":{"$ref":"#/components/schemas/CandidateResult"},"description":"Present when candidates were given"},"timing":{"type":"array","description":"NIH ODS timing statements that apply to this stack (calcium dose size and form, calcium and iron, iron and zinc, iron with food, vitamin D with fat, green tea extract with food, and medication timing for in-stack interactions): id, nutrient_ids, product_refs, advice, advice_es, source. Summary form: the advice strings, in Spanish with \"lang\": \"es\".","items":{"type":"object"}},"foods":{"type":"object","description":"Present with \"foods\": source (USDA SR28), items (how each food was matched: ndb_number, description, confidence, grams, portion used, alternatives, nutrients not analyzed) and totals (per nutrient from the foods; food-only nutrients carry percent_of_ul and flags). Supplement totals with the foods added are in nutrient_totals[].with_foods."},"botanicals":{"type":"array","description":"Present when the stack contains a botanical or other non-nutrient ingredient with an NIH NCCIH/ODS safety signal (ashwagandha, kava, St. John's wort, ginkgo, green tea extract, turmeric, black cohosh, garcinia, red yeast rice, goldenseal, berberine, yohimbe, ephedra, valerian, echinacea, garlic, Asian ginseng, saw palmetto, milk thistle, licorice root, bitter orange, fenugreek, cinnamon, creatine). Matched exactly on the DSLD ingredient group or name. Each has signals (kind, summary), the pregnancy statement, dose_findings (creatine, EGCG, valerian amounts against cited doses) and the source. Summary form: id, name, product_refs, signal, dose.","items":{"type":"object"}},"interactions":{"type":"object","description":"Present when medications or conditions were given. Full form: scope, reviewed, medications (how each name was matched) and findings (all NIH-listed interactions, those involving nutrients in the stack first). Summary form: medications, in-stack findings, and a not_in_stack count.","properties":{"scope":{"type":"string"},"reviewed":{"type":"string"},"medications":{"type":"array","items":{"$ref":"#/components/schemas/MedicationMatch"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/InteractionFinding"}},"not_in_stack":{"type":"integer"}}},"nutrient_totals":{"type":"array","items":{"$ref":"#/components/schemas/NutrientTotal"}},"overlaps":{"type":"array","items":{"type":"object","properties":{"nutrient_id":{"type":"string"},"product_refs":{"type":"array","items":{"type":"string"}}}}},"unrecognized_ingredients":{"type":"array","items":{"$ref":"#/components/schemas/UnrecognizedIngredient"}},"data_gaps":{"type":"array","items":{"$ref":"#/components/schemas/DataGap"}},"products":{"type":"array","items":{"type":"object","properties":{"product_ref":{"type":"string"},"dsld_id":{"type":["integer","null"]},"brand":{"type":["string","null"]},"name":{"type":"string"},"servings_per_day_used":{"type":"number"},"servings_source":{"type":"string","enum":["request","label_maximum","default"]},"entry_date":{"type":["string","null"]},"source_url":{"type":["string","null"]}}}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/interactions/check":{"post":{"summary":"Medication and condition interactions","description":"Vitamin and mineral interactions for the given medications (generic or brand names, normalized with NIH RxNorm when the name is not in the list) and conditions, as listed in the NIH Office of Dietary Supplements fact sheets. Not exhaustive. To check an actual stack, pass medications to /v1/stack/analyze.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"medications":{"minItems":1,"maxItems":30,"type":"array","items":{"type":"string","minLength":2,"maxLength":100},"description":"Medications the person takes, as generic or brand names (\"warfarin\", \"Synthroid\", \"metformin 500 mg\"). Checked against the medication interactions listed in the NIH ODS fact sheets; not exhaustive. Never logged."},"conditions":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["smoker","kidney_disease","hemochromatosis","lab_test_soon","cancer_treatment"]},"description":"Conditions that change how NIH reads a dose: smoker (current or former, or asbestos exposure: beta-carotene), kidney_disease (potassium, magnesium, phosphorus), hemochromatosis (iron, vitamin C), lab_test_soon (biotin interferes with lab tests), cancer_treatment (antioxidant doses)"},"nutrients":{"description":"Optional: only report interactions involving these nutrients or botanicals (IDs or names, e.g. \"vitamin-k\", \"magnesium\", \"St. John's wort\")","minItems":1,"maxItems":40,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"additionalProperties":false},"examples":{"levothyroxine":{"value":{"medications":["levothyroxine"]}},"warfarin_vitamin_k":{"value":{"medications":["Coumadin"],"nutrients":["vitamin k"]}},"condition":{"value":{"conditions":["kidney_disease"]}}}}}},"responses":{"200":{"description":"Interactions","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","const":"dietary-supplement-analysis"},"version":{"type":"string"},"as_of":{"type":"string","format":"date"},"summary":{"type":"object","properties":{"medications":{"type":"integer"},"medications_recognized":{"type":"integer"},"findings":{"type":"integer"}}},"scope":{"type":"string"},"reviewed":{"type":"string"},"medications":{"type":"array","items":{"$ref":"#/components/schemas/MedicationMatch"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/InteractionFinding"}},"data_gaps":{"type":"array","items":{"$ref":"#/components/schemas/DataGap"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string"}}}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/provenance":{"get":{"summary":"Code and data provenance","description":"Service version, git commit (link to the exact source), and the edition or review date of each data source.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/tools":{"get":{"summary":"Tool definitions for function calling","description":"Every operation as {name, path, description, input_schema} (JSON Schema). Call them via their path or POST /v1/tool.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/guide":{"get":{"summary":"Usage guide for agents","description":"Markdown guide (the same text as llms.txt in the repository) inside a JSON object.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"guide":{"type":"string"}}}}}}}}},"/v1/tool":{"post":{"summary":"Tool dispatcher","description":"MCP-style call: {\"tool\": \"stack_analyze\", \"arguments\": {...}}. Returns the same body as the matching route.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"description":"Which tool to run. Defaults to stack_analyze","type":"string","enum":["products_search","products_get","products_lookup","nutrients_reference","stack_analyze","interactions_check","products_fda_reports"]},"name":{"description":"Same as tool (the MCP tools/call field name)","type":"string","enum":["products_search","products_get","products_lookup","nutrients_reference","stack_analyze","interactions_check","products_fda_reports"]},"arguments":{"default":{},"description":"The tool's input, as in GET /v1/tools","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}}}}},"responses":{"200":{"description":"Result of the dispatched tool","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_INPUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND (unknown DSLD ID or nutrient)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"UNSUPPORTED (pregnancy or lactation outside ages 14-50)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"UPSTREAM_UNAVAILABLE: NIH DSLD unreachable and nothing cached (retryable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"retrieved":{"type":"string"}},"required":["name","url","retrieved"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_INPUT","NOT_FOUND","UNSUPPORTED","UPSTREAM_UNAVAILABLE","INTERNAL_ERROR","RATE_LIMITED"]},"message":{"type":"string"},"retryable":{"type":"boolean"},"field":{"type":"string"}},"required":["code","message","retryable"]}},"required":["error"]},"MedicationMatch":{"type":"object","properties":{"input":{"type":"string"},"status":{"type":"string","enum":["matched","not_recognized"]},"matched_name":{"type":["string","null"]},"via":{"oneOf":[{"type":"string","enum":["name","rxnorm"]},{"type":"null"}],"description":"\"rxnorm\": the name was normalized to its ingredient with NIH RxNav"},"classes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"InteractionFinding":{"type":"object","properties":{"type":{"type":"string","enum":["medication","condition"]},"trigger":{"type":"string","description":"The medication as given, or the condition id"},"trigger_name":{"type":"string"},"nutrient_ids":{"type":"array","items":{"type":"string"}},"botanical_ids":{"type":"array","items":{"type":"string"},"description":"Botanicals involved, for botanical-medication interactions (St. John's wort, ginkgo, kava...)"},"in_stack":{"type":"boolean","description":"True when the stack supplies one of the nutrients (condition findings: at or above the checked dose)"},"product_refs":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["supplement_changes_drug","drug_lowers_nutrient","drug_raises_nutrient","additive_risk","two_way","condition"]},"summary":{"type":"string"},"timing":{"type":["string","null"]},"source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}}}},"DataGap":{"type":"object","properties":{"code":{"type":"string","enum":["BLEND_UNQUANTIFIED","QUANTITY_MISSING","UNIT_NOT_CONVERTIBLE","COMPOUND_WEIGHT","AMBIGUOUS_BASIS","UL_PARTIAL","UL_NOT_ASSESSED","NO_REFERENCE","PROFILE_MISSING","SERVINGS_UNKNOWN","DATA_SUSPECT","PRODUCT_NOT_RESOLVED","INTERACTIONS_NOT_ASSESSED","INTERACTIONS_PARTIAL","MEDICATION_NOT_RECOGNIZED","FDA_UNAVAILABLE","FOOD_NOT_RESOLVED","FOOD_PORTION_UNKNOWN"]},"product_ref":{"type":"string"},"nutrient_id":{"type":"string"},"check":{"type":"string","enum":["duplicate_row","nested_exceeds_parent","percent_dv_mismatch","implausible_amount"],"description":"DATA_SUSPECT only: which consistency check on the DSLD record failed"},"detail":{"type":"string"}},"required":["code","detail"]},"Serving":{"type":"object","properties":{"quantity":{"type":["number","null"]},"unit":{"type":["string","null"]},"daily_servings":{"type":"object","properties":{"min":{"type":["number","null"]},"max":{"type":["number","null"]}}},"label_text":{"type":["string","null"]}}},"Ingredient":{"type":"object","properties":{"label_name":{"type":"string"},"nutrient_id":{"type":"string"},"nutrient_name":{"type":"string"},"matched_by":{"type":"string","enum":["ingredient_group","unii","name","form"]},"forms":{"type":"array","items":{"type":"string"}},"form_kind":{"type":["string","null"]},"per_serving":{"oneOf":[{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},{"type":"null"}],"description":"Per serving in the nutrient canonical unit; null if missing or not convertible"},"label_amount":{"oneOf":[{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},{"type":"null"}],"description":"As declared on the label"},"conversion_note":{"type":["string","null"]},"percent_dv":{"type":["number","null"]},"in_blend":{"type":"boolean"},"blend_name":{"type":"string"}}},"UnrecognizedIngredient":{"type":"object","properties":{"product_ref":{"type":"string"},"label_name":{"type":"string"},"category":{"type":["string","null"]},"per_serving":{"oneOf":[{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},{"type":"null"}]},"in_blend":{"type":"boolean"},"is_blend":{"type":"boolean"}}},"ProductSummary":{"type":"object","properties":{"dsld_id":{"type":"integer"},"brand":{"type":["string","null"]},"name":{"type":"string"},"upc":{"type":["string","null"]},"on_market":{"type":["boolean","null"]},"entry_date":{"type":["string","null"],"description":"Date this label version was entered into DSLD"},"other_versions":{"type":"array","items":{"type":"integer"},"description":"DSLD IDs of older versions of the same product"},"serving":{"$ref":"#/components/schemas/Serving"},"ingredient_count":{"type":"integer"},"nutrient_ids":{"type":"array","items":{"type":"string"}},"source_url":{"type":"string"}}},"Label":{"type":"object","properties":{"dsld_id":{"type":"integer"},"brand":{"type":["string","null"]},"name":{"type":"string"},"upc":{"type":["string","null"]},"on_market":{"type":["boolean","null"]},"entry_date":{"type":["string","null"]},"serving":{"$ref":"#/components/schemas/Serving"},"ingredient_count":{"type":"integer"},"source_url":{"type":"string"},"ingredients":{"type":"array","items":{"$ref":"#/components/schemas/Ingredient"}},"unrecognized_ingredients":{"type":"array","items":{"$ref":"#/components/schemas/UnrecognizedIngredient"}},"data_gaps":{"type":"array","items":{"$ref":"#/components/schemas/DataGap"}},"statements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}}},"Reference":{"type":"object","properties":{"rda":{"type":["number","null"]},"ear":{"type":["number","null"]},"ai":{"type":["number","null"]},"ul":{"type":["number","null"]},"unit":{"type":"string"},"ul_unit":{"type":["string","null"]},"ul_scope":{"type":"string"},"ul_note":{"type":["string","null"]},"ul_basis":{"type":["string","null"],"description":"What the UL protects against (the critical adverse effect it is based on)"}}},"NutrientTotal":{"type":"object","properties":{"nutrient_id":{"type":"string"},"name":{"type":"string"},"daily_total":{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},"complete":{"type":"boolean","description":"False when some label rows could not be counted; the total is then a lower bound"},"reference":{"oneOf":[{"$ref":"#/components/schemas/Reference"},{"type":"null"}]},"amount_toward_ul":{"oneOf":[{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},{"type":"null"}],"description":"The part of the total the UL applies to (e.g. folic acid, preformed vitamin A)"},"percent_of_ul":{"type":["number","null"]},"percent_of_rda":{"type":["number","null"]},"percent_of_ai":{"type":["number","null"]},"coverage":{"oneOf":[{"type":"object","properties":{"reference":{"type":"string","enum":["rda","ai"]},"percent":{"type":"number"}},"required":["reference","percent"]},{"type":"null"}],"description":"Percent of the RDA (or AI) supplied by these supplements alone. Informational: diet normally supplies the rest"},"flags":{"type":"array","items":{"type":"string","enum":["above_ul","near_ul"]},"description":"above_ul: the amount the UL applies to exceeds it. near_ul: 90-100% of the UL. No flag means nothing to report"},"severity":{"type":["string","null"],"enum":["high","moderate","low",null],"description":"high: 2x the UL or more; moderate: above the UL; low: within 10% of the UL"},"factsheet_url":{"type":"string"},"contributions":{"type":"array","items":{"type":"object","properties":{"product_ref":{"type":"string"},"label_name":{"type":"string"},"label_amount":{"type":["string","null"]},"converted":{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},"servings_per_day":{"type":"number"},"daily":{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},"daily_toward_ul":{"type":["number","null"]}}}}}},"Resolution":{"type":"object","description":"How a {query} or {upc} product was identified","properties":{"input_path":{"type":"string","description":"e.g. products.0 or candidates.1"},"input":{"type":"object"},"status":{"type":"string","enum":["resolved","not_found"]},"matched_by":{"type":"string","enum":["query","upc"]},"dsld_id":{"type":["integer","null"]},"product_ref":{"type":["string","null"]},"brand":{"type":["string","null"]},"name":{"type":["string","null"]},"entry_date":{"type":["string","null"]},"confidence":{"type":["string","null"],"enum":["high","medium","low",null]},"reason":{"type":"string"},"other_versions":{"type":"array","items":{"type":"integer"}},"alternatives":{"type":"array","items":{"type":"object","properties":{"dsld_id":{"type":"integer"},"brand":{"type":["string","null"]},"name":{"type":["string","null"]},"entry_date":{"type":["string","null"]},"on_market":{"type":["boolean","null"]},"score":{"type":"number"}}}}}},"Suggestion":{"type":"object","description":"A single-product change and its arithmetic effect on an above-UL nutrient","properties":{"nutrient_id":{"type":"string"},"action":{"type":"string","enum":["reduce_servings","remove_product"]},"product_ref":{"type":"string"},"product_name":{"type":"string"},"servings_per_day":{"type":"number","description":"reduce_servings only"},"resolves":{"type":"boolean","description":"True when this change alone brings the amount to or under the UL"},"result":{"type":"object","properties":{"amount_toward_ul":{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},"percent_of_ul":{"type":"number"}}},"also_resolves":{"type":"array","items":{"type":"string"}},"also_lowers":{"type":"array","items":{"type":"string"}},"text":{"type":"string"}}},"CandidateResult":{"type":"object","description":"Effect of adding one candidate product to the stack","properties":{"product_ref":{"type":"string"},"product_name":{"type":"string"},"verdict":{"type":"string","enum":["adds_above_ul","increases_above_ul","adds_near_ul","no_new_flags"]},"new_flags":{"type":"array","items":{"type":"object","properties":{"nutrient_id":{"type":"string"},"name":{"type":"string"},"flag":{"type":"string"},"percent_of_ul":{"type":["number","null"]}}}},"changes":{"type":"array","items":{"type":"object","properties":{"nutrient_id":{"type":"string"},"from":{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},"to":{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"]},"percent_of_ul_to":{"type":["number","null"]},"coverage_percent_to":{"type":["number","null"]}}}},"text":{"type":"string"}}}}}}