{"openapi":"3.1.0","info":{"title":"Plate API","version":"0.1.0","description":"What's in the food, what it means, and what to buy instead: packaged foods, generic foods, recalls, allergens, additives, daily targets.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://plate.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/plate/docs"},"termsOfService":"https://connectorbay.com/plate/terms"},"servers":[{"url":"https://plate.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/plate/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/lookup_product":{"post":{"operationId":"lookup_product","summary":"Everything on record for a packaged food, by barcode or name: nutrition per serving and per 100 g with %DV and","description":"Everything on record for a packaged food, by barcode or name: nutrition per serving and per 100 g with %DV and\n    FDA low/high flags, Nutri-Score and NOVA processing group, allergens and traces, ingredients, additives by plain\n    name, labels (organic, kosher, vegan…), and a plain-English verdict with the one thing to watch. Use for \"what's\n    in this\", \"is this healthy\", \"scan this barcode\", \"tell me about <product>\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"A barcode (digits) or a product name with brand, e.g. 'Cheerios' or 'Chobani vanilla greek yogurt'.","examples":["016000275287","Kind dark chocolate nuts & sea salt bar"],"title":"Query","type":"string"}},"required":["query"],"title":"lookup_productArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_products":{"post":{"operationId":"search_products","summary":"Find packaged products by words in their name (U.S. market first), with barcode, brand, Nutri-Score, NOVA group and","description":"Find packaged products by words in their name (U.S. market first), with barcode, brand, Nutri-Score, NOVA group and\n    calories/sugar/sodium per 100 g so the person can pick the right one before lookup_product. Use when the user names a\n    product without a barcode, or wants to compare a few brands of the same thing.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Words from the product name, e.g. 'greek yogurt vanilla', 'oat milk'.","examples":["greek yogurt vanilla","sparkling water lemon"],"title":"Query","type":"string"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional brand filter, e.g. 'Chobani'.","title":"Brand"},"limit":{"default":10,"description":"Maximum results.","maximum":25,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"search_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compare_products":{"post":{"operationId":"compare_products","summary":"Side-by-side nutrition for two to five packaged foods (per serving or per 100 g) with %DV, plus who wins on","description":"Side-by-side nutrition for two to five packaged foods (per serving or per 100 g) with %DV, plus who wins on\n    sugar, sodium, saturated fat, fibre and protein and a one-line call. Use for \"which is better, A or B\", \"compare\n    these two cereals\", \"lowest sugar of these\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"description":"Two to five barcodes or product names.","examples":[["Cheerios","Honey Nut Cheerios","Kashi GO Original"]],"items":{"type":"string"},"maxItems":5,"minItems":2,"title":"Items","type":"array"},"per":{"default":"serving","description":"'serving' (each product's own serving) or '100g' (like-for-like).","examples":["serving","100g"],"title":"Per","type":"string"}},"required":["items"],"title":"compare_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/allergen_check":{"post":{"operationId":"allergen_check","summary":"Check a packaged food against the allergens a person avoids: 'declared' (on the label's allergen statement), 'may contai","description":"Check a packaged food against the allergens a person avoids: 'declared' (on the label's allergen statement), 'may contain'\n    (traces statement), 'found in ingredients' (a matching word in the list), or 'not found' — with the evidence and an explicit\n    caveat that the package is the authority. Use for \"does this have dairy\", \"is this safe for a peanut allergy\", \"any sesame\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"A barcode (digits) or a product name with brand, e.g. 'Cheerios' or 'Chobani vanilla greek yogurt'.","examples":["016000275287","Kind dark chocolate nuts & sea salt bar"],"title":"Query","type":"string"},"allergens":{"description":"What the person avoids, e.g. ['milk', 'peanuts', 'sesame']. The nine U.S. major allergens are milk, eggs, fish, shellfish, tree nuts, peanuts, wheat, soy, sesame; any other word is matched literally against the ingredients.","items":{"type":"string"},"maxItems":10,"minItems":1,"title":"Allergens","type":"array"}},"required":["query","allergens"],"title":"allergen_checkArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/decode_ingredients":{"post":{"operationId":"decode_ingredients","summary":"Read an ingredient list the way a dietitian would: every additive by plain name and function (with regulatory notes wher","description":"Read an ingredient list the way a dietitian would: every additive by plain name and function (with regulatory notes where an\n    authority has acted), added sugars under all their names and where the first one sits in the list, non-nutritive sweeteners,\n    allergen words, and the markers that make a food 'ultra-processed'. Accepts a barcode, a product name, or pasted text (e.g.\n    typed from a photo). Use for \"what is tripotassium phosphate\", \"how many kinds of sugar are in this\", \"is this ultra-processed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"A barcode, a product name, or the ingredient list itself pasted from the package.","examples":["016000275287","Whole grain oats, sugar, corn syrup, salt, tripotassium phosphate, natural flavor, mixed tocopherols"],"title":"Query","type":"string"}},"required":["query"],"title":"decode_ingredientsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/swap_suggestions":{"post":{"operationId":"swap_suggestions","summary":"Better options in the same product category (sold in the U.S.), ranked for the goal, with the numbers per 100 g next","description":"Better options in the same product category (sold in the U.S.), ranked for the goal, with the numbers per 100 g next\n    to the original so the improvement is concrete. Use for \"something like this with less sugar\", \"a healthier version\",\n    \"lower-sodium alternative\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"A barcode (digits) or a product name with brand, e.g. 'Cheerios' or 'Chobani vanilla greek yogurt'.","examples":["016000275287","Kind dark chocolate nuts & sea salt bar"],"title":"Query","type":"string"},"goal":{"default":"better_overall","description":"What to improve: less_sugar, less_sodium, less_saturated_fat, more_fiber, more_protein, less_processed, better_overall (Nutri-Score).","examples":["less_sugar","more_fiber"],"title":"Goal","type":"string"},"limit":{"default":8,"description":"Maximum results.","maximum":25,"minimum":1,"title":"Limit","type":"integer"}},"required":["query"],"title":"swap_suggestionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/nutrition":{"post":{"operationId":"nutrition","summary":"Calories and nutrients for a generic (unbranded) food in the amount asked — with %DV, FDA low/high flags, the household","description":"Calories and nutrients for a generic (unbranded) food in the amount asked — with %DV, FDA low/high flags, the household\n    portions on record (1 large, 1 cup…) and the exact USDA record matched so the person can correct it. Use for \"how much\n    protein in two eggs\", \"calories in a banana\", \"sodium in a cup of canned soup\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"food":{"description":"A generic food, optionally with an amount: 'egg', '2 large eggs', '1 cup cooked brown rice', '3 oz salmon', 'banana'.","examples":["2 large eggs","1 cup cooked brown rice","banana"],"title":"Food","type":"string"},"amount":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Quantity, if not written in `food`.","title":"Amount"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Unit for `amount`: g, oz, cup, tbsp, slice, large, serving… (matched to the food's own household portions).","title":"Unit"}},"required":["food"],"title":"nutritionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/meal_tally":{"post":{"operationId":"meal_tally","summary":"Add up a meal or a day: calories, protein, fibre, sugars, sodium, saturated fat and more across the foods listed (generi","description":"Add up a meal or a day: calories, protein, fibre, sugars, sodium, saturated fat and more across the foods listed (generic USDA\n    foods with household portions), as %DV and — when age and sex are given — as a share of that person's daily targets, with\n    what is high and what is missing. Use for \"add up my breakfast\", \"how much sodium was that\", \"did I get enough fibre today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"description":"Foods with amounts, one per entry: ['2 scrambled eggs', '2 slices whole wheat bread', '1 tbsp butter', '1 cup orange juice'].","items":{"type":"string"},"maxItems":20,"minItems":1,"title":"Items","type":"array"},"age":{"anyOf":[{"maximum":110,"minimum":2,"type":"integer"},{"type":"null"}],"default":null,"description":"Person's age, to size the totals against their daily targets (optional).","title":"Age"},"sex":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'female' or 'male' (optional, with age).","title":"Sex"},"activity":{"default":"moderate","description":"sedentary, moderate or active (with age).","title":"Activity","type":"string"}},"required":["items"],"title":"meal_tallyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/daily_targets":{"post":{"operationId":"daily_targets","summary":"What a person of this age, sex and activity level should aim for in a day per the Dietary Guidelines for Americans 2020-","description":"What a person of this age, sex and activity level should aim for in a day per the Dietary Guidelines for Americans 2020-2025:\n    calories, MyPlate amounts (vegetables, fruit, grains, protein, dairy, oils), maximum added sugars, saturated fat and sodium, and a\n    fibre target. Use for \"how much should my 9-year-old eat\", \"what's a normal sodium limit\", \"how many cups of vegetables a day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"age":{"description":"Age in years (2–110).","maximum":110,"minimum":2,"title":"Age","type":"integer"},"sex":{"description":"'female' or 'male' (the Dietary Guidelines tables are by sex).","examples":["female","male"],"title":"Sex","type":"string"},"activity":{"default":"moderate","description":"sedentary, moderate or active.","examples":["moderate"],"title":"Activity","type":"string"}},"required":["age","sex"],"title":"daily_targetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/food_recalls":{"post":{"operationId":"food_recalls","summary":"Recent U.S. food recalls from FDA (all foods except meat, poultry and processed egg products) and USDA-FSIS (meat, poult","description":"Recent U.S. food recalls from FDA (all foods except meat, poultry and processed egg products) and USDA-FSIS (meat, poultry,\n    egg products), newest first, with the reason, class (I = serious), the products and lot codes affected, where they were sold,\n    and what to do. Use for \"any recalls on X\", \"is there a listeria recall right now\", \"recalls in my state this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Product, brand, ingredient or reason words, e.g. 'peanut butter', 'listeria', 'Trader Joe's'. Leave empty for the latest recalls.","examples":["listeria","baby formula","cucumbers"],"title":"Query"},"days":{"default":90,"description":"How far back, in days (1–365).","maximum":365,"minimum":1,"title":"Days","type":"integer"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter state to include recalls distributed there or nationwide, e.g. 'CA'.","title":"State"},"limit":{"default":15,"description":"Maximum results.","maximum":25,"minimum":1,"title":"Limit","type":"integer"}},"title":"food_recallsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/pantry_recall_check":{"post":{"operationId":"pantry_recall_check","summary":"Check a list of products against recent FDA (and, when reachable, USDA-FSIS) recalls: for each item, the matching recall","description":"Check a list of products against recent FDA (and, when reachable, USDA-FSIS) recalls: for each item, the matching recalls\n    by product words and brand, so the person knows what to look at and what is clear. Barcodes are resolved to names first.\n    Use for \"is anything in my pantry recalled\", \"check these for recalls\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"description":"Products the person has, as names or barcodes: ['Jif peanut butter', 'Kirkland organic spinach', '016000275287'].","items":{"type":"string"},"maxItems":25,"minItems":1,"title":"Items","type":"array"},"days":{"default":180,"description":"How far back to search recalls, in days (1–365).","maximum":365,"minimum":1,"title":"Days","type":"integer"}},"required":["items"],"title":"pantry_recall_checkArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/additive_lookup":{"post":{"operationId":"additive_lookup","summary":"What an additive is and what it does, by name or E-number: plain name, function class (colour, preservative, emulsifier…","description":"What an additive is and what it does, by name or E-number: plain name, function class (colour, preservative, emulsifier…)\n    and any regulatory note (an authority that has restricted or revoked it). Use for \"what is E471\", \"is red 40 banned\",\n    \"why is there xanthan gum in this\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"names":{"description":"Additive names or E-numbers: ['tripotassium phosphate', 'E621', 'carrageenan', 'red 40'].","items":{"type":"string"},"maxItems":15,"minItems":1,"title":"Names","type":"array"}},"required":["names"],"title":"additive_lookupArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/sources":{"post":{"operationId":"sources","summary":"Where Plate's data comes from, its licences, coverage and known gaps — so the agent can answer \"where is this from\"","description":"Where Plate's data comes from, its licences, coverage and known gaps — so the agent can answer \"where is this from\"\n    and set expectations (e.g. Open Food Facts completeness, FSIS reachability, USDA release date).","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"sourcesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}