Check a list of dietary supplements for a person: per-nutrient daily totals against NIH upper limits (UL) and RDA/AI, which products overlap, what each UL protects against, and single-product changes that would bring an above-UL nutrient back under it. Products can be given as names ("Centrum Silver Women 50+"), barcodes, DSLD IDs, or custom ingredient lists; optional candidates are evaluated as additions. Pass the person's medications and conditions (smoker, kidney_disease, hemochromatosis, lab_test_soon, cancer_treatment) to check them against the interactions in the NIH fact sheets. Returns agent_summary (plain sentences to relay), resolutions, suggestions, interactions, nutrient_totals and data_gaps. Label data only; food is included only with diet "typical".
View input 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"
]
}