{"openapi":"3.0.0","info":{"version":"1.0.0","title":"V0 Hono API","description":"API Documentation powered by @hono/zod-openapi and Scalar"},"servers":[{"url":"https://api.rambh.com","description":"API Server"}],"components":{"schemas":{"ApiResponse_Data":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true},"status":{"type":"number","example":200},"message":{"type":"string","example":"Food categories retrieved successfully"},"data":{"type":"array","items":{"$ref":"#/components/schemas/FoodCategory"}},"error":{"nullable":true,"example":null}},"required":["success","status","message","data","error"]},"FoodCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"code":{"type":"string","example":"dairy"},"label":{"type":"string","example":"Dairy & Dairy Alternatives"}},"required":["id","code","label"]},"PaginatedResponse_Items":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true},"status":{"type":"number","example":200},"message":{"type":"string","example":"Ingredients retrieved successfully"},"data":{"type":"array","items":{"$ref":"#/components/schemas/IngredientDetail"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"error":{"nullable":true,"example":null}},"required":["success","status","message","data","pagination","error"]},"IngredientDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440001"},"entityId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440002"},"version":{"type":"number","example":1},"isCurrent":{"type":"boolean","example":true},"status":{"type":"string","enum":["draft","approved","published","archived"],"example":"approved"},"canonicalName":{"type":"string","example":"Whole Milk"},"categoryId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440003"},"vendorId":{"type":"string","nullable":true,"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440080"},"vendor":{"$ref":"#/components/schemas/Vendor"},"isLiquid":{"type":"boolean","example":true,"description":"Whether the ingredient is in liquid state"},"densityGMl":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"1.0320","description":"Density in g/mL at 20°C for volumetric conversions"},"internalId":{"type":"string","nullable":true,"example":"ING-2026-0842","description":"Internal Ingredient ID #"},"description":{"type":"string","nullable":true,"example":"Cold-pressed organic orange oil extract","description":"Technical substance description"},"bulkDensity":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"0.8420","description":"Bulk Density / Specific Gravity"},"particleNature":{"type":"string","nullable":true,"example":"Fine powder","description":"Particle nature (e.g. Fine powder, Granular, Liquid, Flakes)"},"potencyPercent":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"98.5","description":"% Potency / Active Assay"},"color":{"type":"string","nullable":true,"example":"Off-white to light cream","description":"Color and sensory appearance"},"dateOfReceipt":{"type":"string","nullable":true,"example":"2026-09-30","description":"Date of Receipt"},"specSheetScanned":{"anyOf":[{"type":"boolean"},{"type":"string"},{"nullable":true}],"example":"Yes","description":"Specification Sheet Scanned (Yes/No)"},"coaScanned":{"anyOf":[{"type":"boolean"},{"type":"string"},{"nullable":true}],"example":"Yes","description":"COA Scanned (Yes/No)"},"qtyReceived":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"250","description":"QTY received"},"qtyReceivedUnit":{"type":"string","nullable":true,"enum":["kg","gm","ltr","ml",null],"example":"kg","description":"QTY unit"},"specSheetUrl":{"type":"string","nullable":true},"coaUrl":{"type":"string","nullable":true},"storageLocation":{"type":"string","nullable":true,"example":"Warehouse B - Aisle 4 - Rack 2","description":"Storage Location"},"vendorLotNumber":{"type":"string","nullable":true,"example":"LOT-2026-09A","description":"Vendor Lot #"},"vendorName":{"type":"string","nullable":true,"example":"Kerry Ingredients Inc.","description":"Vendor Name"},"vendorIngredientId":{"type":"string","nullable":true,"example":"KRY-FLV-9901","description":"Vendor System Ingredient ID #"},"costPerKg":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"48.50","description":"Cost / per kg"},"tieredPricing":{"anyOf":[{"type":"string"},{"type":"array","items":{"nullable":true}},{"nullable":true}],"example":"1-100kg: $48.50, >500kg: $42.00","description":"Tiered price structure"},"leadTimeDays":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"14","description":"Lead time (days)"},"moq":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"25","description":"MOQ"},"vendorContactName":{"type":"string","nullable":true,"example":"Sarah Jenkins","description":"Contact Name"},"vendorContactEmail":{"type":"string","nullable":true,"example":"sarah.j@kerry.com","description":"Contact Email"},"vendorContactPhone":{"type":"string","nullable":true,"example":"+1 (555) 234-5678","description":"Contact Phone"},"projectCustomer":{"type":"string","nullable":true,"example":"Project Citrus / Nestle USA","description":"Project Customer"},"additionalComments":{"type":"string","nullable":true,"example":"Store below 25°C under dry nitrogen blanket","description":"Additional Comments"},"createdBy":{"type":"string","example":"developer"},"createdAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"example":"2026-09-28T12:00:00.000Z"},"updatedBy":{"type":"string","nullable":true,"example":"developer"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"example":"2026-09-28T12:00:00.000Z"},"metadata":{"nullable":true},"category":{"$ref":"#/components/schemas/FoodCategory"},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IngredientIdentifier"}},"nutrientLinks":{"type":"array","items":{"$ref":"#/components/schemas/IngredientNutrient"}},"allergenLinks":{"type":"array","items":{"$ref":"#/components/schemas/IngredientAllergen"}}},"required":["id","entityId","version","isCurrent","status","canonicalName","categoryId","isLiquid","densityGMl","createdAt","updatedAt"]},"Vendor":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440080"},"name":{"type":"string","example":"Kerry Ingredients Inc."},"code":{"type":"string","nullable":true,"example":"VND-KRY-01"},"contactName":{"type":"string","nullable":true,"example":"Sarah Jenkins"},"contactEmail":{"type":"string","nullable":true,"example":"sarah.j@kerry.com"},"contactPhone":{"type":"string","nullable":true,"example":"+1 (555) 234-5678"},"address":{"type":"string","nullable":true,"example":"3333 Kerry Way, Beloit, WI 53511"},"country":{"type":"string","nullable":true,"example":"United States"},"website":{"type":"string","nullable":true,"example":"https://www.kerry.com"},"status":{"type":"string","enum":["active","inactive","pending_approval"],"default":"active","example":"active","description":"Vendor operational status"},"notes":{"type":"string","nullable":true,"example":"Global supplier for flavor systems and citrus extracts"},"createdBy":{"type":"string","example":"developer"},"createdAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}]},"updatedBy":{"type":"string","nullable":true},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}]},"metadata":{"nullable":true},"ingredientCount":{"type":"number","default":0,"example":12}},"required":["id","name"]},"IngredientIdentifier":{"allOf":[{"$ref":"#/components/schemas/IngredientIdentifierInput"},{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440010"},"ingredientId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440020"},"createdAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"example":"2026-09-28T12:00:00.000Z"}},"required":["id","ingredientId","createdAt"]}]},"IngredientIdentifierInput":{"type":"object","properties":{"identifierType":{"type":"string","example":"CAS","description":"Identifier system (e.g. CAS, UNII, INS, E_NUMBER, SAP_CODE)"},"identifierValue":{"type":"string","example":"50-99-7","description":"Identifier code or string"},"authority":{"type":"string","nullable":true,"example":"GLOBAL","description":"Jurisdiction or organization"},"notes":{"type":"string","nullable":true,"example":"Primary CAS Registry Number","description":"Contextual notes"}},"required":["identifierType","identifierValue"]},"IngredientNutrient":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440040"},"ingredientId":{"type":"string","format":"uuid"},"nutrientId":{"type":"string","format":"uuid"},"amount":{"anyOf":[{"type":"string"},{"type":"number"}],"example":"3.400000"},"unit":{"type":"string","enum":["g","mg","mcg","iu","kcal","kj","ppm"],"example":"g"},"basis":{"type":"string","enum":["per_100g","per_100ml"],"example":"per_100g"},"nutrient":{"$ref":"#/components/schemas/Nutrient"}},"required":["id","ingredientId","nutrientId","amount","unit","basis"]},"Nutrient":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440002"},"code":{"type":"string","example":"protein"},"displayName":{"type":"string","example":"Protein"},"categoryId":{"type":"string","format":"uuid"},"defaultUnit":{"type":"string","minLength":1,"example":"g"},"dailyValue":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"50.000000"},"needsReview":{"type":"boolean","example":false},"createdBy":{"type":"string","example":"Bulk Import"},"createdAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}]},"updatedBy":{"type":"string","nullable":true},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}]},"metadata":{"nullable":true},"ingredientCount":{"type":"number","default":0,"example":38},"category":{"$ref":"#/components/schemas/NutrientCategory"},"aliases":{"type":"array","items":{"$ref":"#/components/schemas/NutrientAlias"}}},"required":["id","code","displayName","categoryId","defaultUnit","dailyValue","needsReview"]},"NutrientCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"code":{"type":"string","example":"macronutrient"},"label":{"type":"string","example":"Macronutrients"},"sortOrder":{"type":"number","example":1}},"required":["id","code","label","sortOrder"]},"NutrientAlias":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440001"},"rawKey":{"type":"string","example":"total_protein"},"confidence":{"anyOf":[{"type":"number"},{"type":"string"}],"example":1},"status":{"type":"string","enum":["pending","approved"],"example":"approved"}},"required":["id","rawKey","confidence","status"]},"IngredientAllergen":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440060"},"ingredientId":{"type":"string","format":"uuid"},"allergenId":{"type":"string","format":"uuid"},"presenceType":{"type":"string","enum":["contains","may_contain_line","may_contain_facility","free_of"],"example":"contains"},"allergen":{"$ref":"#/components/schemas/Allergen"}},"required":["id","ingredientId","allergenId","presenceType"]},"Allergen":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"code":{"type":"string","example":"peanut"},"label":{"type":"string","example":"Peanuts"},"jurisdiction":{"type":"string","nullable":true,"example":"US_FDA"},"createdBy":{"type":"string","example":"Bulk Import"},"createdAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}]},"updatedBy":{"type":"string","nullable":true},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}]},"metadata":{"nullable":true},"ingredientCount":{"type":"number","default":0,"example":42}},"required":["id","code","label","jurisdiction"]},"PaginationMeta":{"type":"object","properties":{"total":{"type":"number","example":42,"description":"Total number of records"},"page":{"type":"number","example":1,"description":"Current page number"},"limit":{"type":"number","example":20,"description":"Number of records per page"},"totalPages":{"type":"number","example":3,"description":"Total number of pages"},"hasNextPage":{"type":"boolean","example":true},"hasPrevPage":{"type":"boolean","example":false}},"required":["total","page","limit","totalPages"]},"ErrorResponse_404":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":404},"message":{"type":"string","example":"Ingredient not found"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"ErrorResponse_400":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":400},"message":{"type":"string","example":"Invalid input"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"CreateIngredientRequest":{"type":"object","properties":{"canonicalName":{"type":"string","minLength":1,"example":"Pasteurized Whole Milk 3.25%"},"categoryId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440003"},"vendorId":{"type":"string","nullable":true,"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440080"},"isLiquid":{"type":"boolean","default":false,"example":true},"densityGMl":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"1.0320","description":"g/mL density (required for liquids in recipe formulations)"},"status":{"type":"string","enum":["draft","approved","published","archived"],"default":"draft","example":"draft"},"internalId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"bulkDensity":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"particleNature":{"type":"string","nullable":true},"potencyPercent":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"color":{"type":"string","nullable":true},"dateOfReceipt":{"type":"string","nullable":true},"specSheetScanned":{"anyOf":[{"type":"boolean"},{"type":"string"},{"nullable":true}]},"coaScanned":{"anyOf":[{"type":"boolean"},{"type":"string"},{"nullable":true}]},"qtyReceived":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"qtyReceivedUnit":{"type":"string","nullable":true,"enum":["kg","gm","ltr","ml",null]},"specSheetUrl":{"type":"string","nullable":true},"coaUrl":{"type":"string","nullable":true},"storageLocation":{"type":"string","nullable":true},"vendorLotNumber":{"type":"string","nullable":true},"vendorName":{"type":"string","nullable":true},"vendorIngredientId":{"type":"string","nullable":true},"costPerKg":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"tieredPricing":{"anyOf":[{"type":"string"},{"type":"array","items":{"nullable":true}},{"nullable":true}]},"leadTimeDays":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"moq":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"vendorContactName":{"type":"string","nullable":true},"vendorContactEmail":{"type":"string","nullable":true},"vendorContactPhone":{"type":"string","nullable":true},"projectCustomer":{"type":"string","nullable":true},"additionalComments":{"type":"string","nullable":true},"createdBy":{"type":"string","example":"developer"},"updatedBy":{"type":"string","example":"developer"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IngredientIdentifierInput"}},"nutrients":{"type":"array","items":{"$ref":"#/components/schemas/IngredientNutrientInput"}},"allergens":{"type":"array","items":{"$ref":"#/components/schemas/IngredientAllergenInput"}}},"required":["canonicalName","categoryId"]},"IngredientNutrientInput":{"type":"object","properties":{"nutrientId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440030"},"amount":{"anyOf":[{"type":"string"},{"type":"number"}],"example":"3.400000","description":"Exact numeric amount per specified basis"},"unit":{"type":"string","enum":["g","mg","mcg","iu","kcal","kj","ppm"],"example":"g"},"basis":{"type":"string","enum":["per_100g","per_100ml"],"default":"per_100g","example":"per_100g"}},"required":["nutrientId","amount","unit"]},"IngredientAllergenInput":{"type":"object","properties":{"allergenId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440050"},"presenceType":{"type":"string","enum":["contains","may_contain_line","may_contain_facility","free_of"],"default":"contains","example":"contains","description":"Granular 4-tier allergen containment level"}},"required":["allergenId"]},"UpdateIngredientRequest":{"type":"object","properties":{"canonicalName":{"type":"string","minLength":1,"example":"Pasteurized Whole Milk 3.25% (Updated)"},"categoryId":{"type":"string","format":"uuid"},"vendorId":{"type":"string","nullable":true,"format":"uuid"},"isLiquid":{"type":"boolean"},"densityGMl":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"status":{"type":"string","enum":["draft","approved","published","archived"]},"internalId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"bulkDensity":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"particleNature":{"type":"string","nullable":true},"potencyPercent":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"color":{"type":"string","nullable":true},"dateOfReceipt":{"type":"string","nullable":true},"specSheetScanned":{"anyOf":[{"type":"boolean"},{"type":"string"},{"nullable":true}]},"coaScanned":{"anyOf":[{"type":"boolean"},{"type":"string"},{"nullable":true}]},"qtyReceived":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"qtyReceivedUnit":{"type":"string","nullable":true,"enum":["kg","gm","ltr","ml",null]},"specSheetUrl":{"type":"string","nullable":true},"coaUrl":{"type":"string","nullable":true},"storageLocation":{"type":"string","nullable":true},"vendorLotNumber":{"type":"string","nullable":true},"vendorName":{"type":"string","nullable":true},"vendorIngredientId":{"type":"string","nullable":true},"costPerKg":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"tieredPricing":{"anyOf":[{"type":"string"},{"type":"array","items":{"nullable":true}},{"nullable":true}]},"leadTimeDays":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"moq":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"vendorContactName":{"type":"string","nullable":true},"vendorContactEmail":{"type":"string","nullable":true},"vendorContactPhone":{"type":"string","nullable":true},"projectCustomer":{"type":"string","nullable":true},"additionalComments":{"type":"string","nullable":true},"updatedBy":{"type":"string","example":"developer"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IngredientIdentifierInput"}},"nutrients":{"type":"array","items":{"$ref":"#/components/schemas/IngredientNutrientInput"}},"allergens":{"type":"array","items":{"$ref":"#/components/schemas/IngredientAllergenInput"}}}},"CreateNutrientInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"example":"vitamin_d"},"displayName":{"type":"string","minLength":1,"example":"Vitamin D"},"categoryId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"defaultUnit":{"type":"string","minLength":1,"example":"mcg"},"dailyValue":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"20.0"},"needsReview":{"type":"boolean","default":false},"createdBy":{"type":"string","example":"developer"},"metadata":{"nullable":true},"aliases":{"type":"array","items":{"type":"string"},"example":["cholecalciferol","ergocalciferol"]}},"required":["code","displayName","categoryId","defaultUnit"]},"UpdateNutrientInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"example":"vitamin_d"},"displayName":{"type":"string","minLength":1,"example":"Vitamin D (Calciferol)"},"categoryId":{"type":"string","format":"uuid"},"defaultUnit":{"type":"string","minLength":1,"example":"mcg"},"dailyValue":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"needsReview":{"type":"boolean"},"updatedBy":{"type":"string","example":"developer"},"metadata":{"nullable":true},"aliases":{"type":"array","items":{"type":"string"}}}},"MergeNutrientInput":{"type":"object","properties":{"targetNutrientId":{"type":"string","format":"uuid","description":"Target canonical nutrient UUID to merge into"},"adoptAliases":{"type":"boolean","default":true,"description":"Transfer all source aliases to target nutrient"},"adoptSourceAsAlias":{"type":"boolean","default":true,"description":"Add source code and display name as new OCR aliases under target"},"updatedBy":{"type":"string","example":"developer"}},"required":["targetNutrientId"]},"CreateAllergenInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"example":"mustard"},"label":{"type":"string","minLength":1,"example":"Mustard & Products Thereof"},"jurisdiction":{"type":"string","nullable":true,"example":"EU_FIC"},"createdBy":{"type":"string","example":"developer"},"metadata":{"nullable":true}},"required":["code","label"]},"UpdateAllergenInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"example":"mustard"},"label":{"type":"string","minLength":1,"example":"Mustard"},"jurisdiction":{"type":"string","nullable":true,"example":"EU_FIC"},"updatedBy":{"type":"string","example":"developer"},"metadata":{"nullable":true}}},"ErrorResponse_409":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":409},"message":{"type":"string","example":"Vendor with this name already exists"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"CreateVendorInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Kerry Ingredients Inc."},"code":{"type":"string","nullable":true,"example":"VND-KRY-01"},"contactName":{"type":"string","nullable":true,"example":"Sarah Jenkins"},"contactEmail":{"type":"string","nullable":true,"format":"email","example":"sarah.j@kerry.com"},"contactPhone":{"type":"string","nullable":true,"example":"+1 (555) 234-5678"},"address":{"type":"string","nullable":true,"example":"3333 Kerry Way, Beloit, WI 53511"},"country":{"type":"string","nullable":true,"example":"United States"},"website":{"type":"string","nullable":true,"example":"https://www.kerry.com"},"status":{"type":"string","enum":["active","inactive","pending_approval"],"default":"active","example":"active","description":"Vendor operational status"},"notes":{"type":"string","nullable":true,"example":"Primary vendor notes"},"createdBy":{"type":"string","example":"developer"},"metadata":{"nullable":true}},"required":["name"]},"UpdateVendorInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Kerry Ingredients Inc."},"code":{"type":"string","nullable":true,"example":"VND-KRY-01"},"contactName":{"type":"string","nullable":true,"example":"Sarah Jenkins"},"contactEmail":{"type":"string","nullable":true,"example":"sarah.j@kerry.com"},"contactPhone":{"type":"string","nullable":true,"example":"+1 (555) 234-5678"},"address":{"type":"string","nullable":true,"example":"3333 Kerry Way, Beloit, WI 53511"},"country":{"type":"string","nullable":true,"example":"United States"},"website":{"type":"string","nullable":true,"example":"https://www.kerry.com"},"status":{"type":"string","enum":["active","inactive","pending_approval"],"example":"active","description":"Vendor operational status"},"notes":{"type":"string","nullable":true,"example":"Updated vendor notes"},"updatedBy":{"type":"string","example":"developer"},"metadata":{"nullable":true}}},"CreateProductInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Citrus Energy Focus Sparkling Tonic"},"code":{"type":"string","example":"PRD-NRG-001"},"description":{"type":"string","example":"Clean label functional nootropic beverage"},"categoryId":{"type":"string","example":"796ef6d5-4bf8-466d-a602-0c9f8df56501"},"targetMarket":{"type":"string","example":"US_FDA"},"format":{"type":"string","example":"beverage_rtd"},"servingSize":{"type":"number","example":250},"servingUnit":{"type":"string","example":"ml"},"targetDensityGMl":{"type":"number","example":1.018},"targetCogsPerUnit":{"type":"number","example":0.45},"dietaryExclusions":{"type":"array","items":{"type":"string"},"example":["vegan","non_gmo","gluten_free"]},"sensoryProfile":{"type":"object","properties":{"flavorNotes":{"type":"string"},"sweetenerPreference":{"type":"string"},"colorPreference":{"type":"string"},"textureViscosity":{"type":"string"}}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/ProductClaimRequirement"}},"createdBy":{"type":"string","example":"developer"}},"required":["name","categoryId"]},"ProductClaimRequirement":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["structure_function","nutrient_content","health_claim","disease_claim_flagged"]},"claimText":{"type":"string"},"targetNutrientOrActive":{"type":"string"},"targetValue":{"type":"string"},"rationaleOrNotes":{"type":"string"},"status":{"type":"string","enum":["target","formulated","verified","flagged"],"default":"target"}},"required":["type","claimText"]},"UpdateFormulationDraftInput":{"type":"object","properties":{"servingSize":{"type":"number","example":250},"servingUnit":{"type":"string","example":"ml"},"densityGMl":{"type":"number","example":1.018},"changeReason":{"type":"string","example":"Optimized L-Theanine to Natural Caffeine ratio"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FormulationLine"}},"skipAudit":{"type":"boolean","example":false,"description":"If true, skips writing immutable audit ledger entry (used for debounced background auto-saves)"},"updatedBy":{"type":"string","example":"developer"}},"required":["lines"]},"FormulationLine":{"type":"object","properties":{"id":{"type":"string"},"ingredientId":{"type":"string"},"classification":{"type":"string","enum":["active","inactive"]},"quantity":{"type":"number"},"unit":{"type":"string"},"percentWW":{"type":"number"},"massG":{"type":"number"},"overagePercent":{"type":"number","example":15},"targetClaimQuantity":{"type":"number","nullable":true,"example":150},"targetClaimUnit":{"type":"string","example":"mg"},"effectiveActiveMassG":{"type":"number"},"vendorId":{"type":"string","nullable":true},"lotNumber":{"type":"string","nullable":true},"functionalRole":{"type":"string","nullable":true},"sortOrder":{"type":"number"},"notes":{"type":"string","nullable":true}},"required":["ingredientId","classification"]},"LockFormulationInput":{"type":"object","properties":{"status":{"type":"string","enum":["locked","submitted","approved"]},"changeReason":{"type":"string"},"lockedBy":{"type":"string"}}},"DuplicateFormulationInput":{"type":"object","properties":{"branchType":{"type":"string","enum":["minor","major"]},"createdBy":{"type":"string"}}}},"parameters":{}},"paths":{"/api/food-categories":{"get":{"tags":["Ingredient"],"summary":"List all food categories","description":"Retrieve all food category classifications (e.g., Dairy, Bakery, Beverage, Sweeteners).","responses":{"200":{"description":"List of food categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/ingredients":{"get":{"tags":["Ingredient"],"summary":"List ingredients catalog","description":"Search, filter, and paginate through master ingredients with full relational data.","parameters":[{"schema":{"type":"string","description":"Page number (default: 1)","example":"1"},"required":false,"description":"Page number (default: 1)","name":"page","in":"query"},{"schema":{"type":"string","description":"Items per page (default: 20, max: 100)","example":"20"},"required":false,"description":"Items per page (default: 20, max: 100)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Search term matching canonical name, vendor, location, lot #, or identifiers"},"required":false,"description":"Search term matching canonical name, vendor, location, lot #, or identifiers","name":"search","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by food category UUID"},"required":false,"description":"Filter by food category UUID","name":"categoryId","in":"query"},{"schema":{"type":"string","enum":["false","true"],"description":"Filter by liquid state"},"required":false,"description":"Filter by liquid state","name":"isLiquid","in":"query"},{"schema":{"type":"string","enum":["approved","published","draft","archived"],"description":"Filter by lifecycle status"},"required":false,"description":"Filter by lifecycle status","name":"status","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include past versions and archived items"},"required":false,"description":"Include past versions and archived items","name":"includeArchived","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter ingredients linking a specific nutrient UUID"},"required":false,"description":"Filter ingredients linking a specific nutrient UUID","name":"nutrientId","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter ingredients carrying a specific allergen UUID"},"required":false,"description":"Filter ingredients carrying a specific allergen UUID","name":"allergenId","in":"query"},{"schema":{"type":"string","description":"Filter by allergen presence level (contains, may_contain_line, etc.)"},"required":false,"description":"Filter by allergen presence level (contains, may_contain_line, etc.)","name":"presenceType","in":"query"},{"schema":{"type":"string","description":"Filter by vendor name"},"required":false,"description":"Filter by vendor name","name":"vendorName","in":"query"},{"schema":{"type":"string","description":"Filter by storage location"},"required":false,"description":"Filter by storage location","name":"storageLocation","in":"query"},{"schema":{"type":"string","description":"Filter by internal ingredient ID #"},"required":false,"description":"Filter by internal ingredient ID #","name":"internalId","in":"query"},{"schema":{"type":"string","description":"Filter by vendor lot #"},"required":false,"description":"Filter by vendor lot #","name":"vendorLotNumber","in":"query"}],"responses":{"200":{"description":"Paginated ingredients list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}}}},"post":{"tags":["Ingredient"],"summary":"Create new ingredient","description":"Create a new ingredient along with optional substance identifiers, nutrient values, and allergen containment levels atomically.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIngredientRequest"}}}},"responses":{"201":{"description":"Ingredient created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/ingredients/{id}":{"get":{"tags":["Ingredient"],"summary":"Get ingredient by ID","description":"Retrieve comprehensive ingredient details with nested category, identifiers, nutrients, and allergen containment levels.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Ingredient version UUID"},"required":true,"description":"Ingredient version UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Ingredient details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Ingredient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"put":{"tags":["Ingredient"],"summary":"Update ingredient (Creates Version N+1)","description":"Performs immutable update by creating version N+1 and archiving the previous version to maintain formulation integrity.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Current ingredient version UUID"},"required":true,"description":"Current ingredient version UUID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIngredientRequest"}}}},"responses":{"200":{"description":"New ingredient version created and activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Ingredient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"delete":{"tags":["Ingredient"],"summary":"Archive ingredient","description":"Soft deletes / archives an ingredient version to preserve formulation history and traceability.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Ingredient version UUID"},"required":true,"description":"Ingredient version UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Ingredient archived successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Ingredient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/ingredients/{id}/versions":{"get":{"tags":["Ingredient"],"summary":"Get ingredient version history","description":"Retrieves all immutable historical version snapshots for the specified ingredient entity.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Ingredient version UUID or entity UUID"},"required":true,"description":"Ingredient version UUID or entity UUID","name":"id","in":"path"}],"responses":{"200":{"description":"List of all historical and active version snapshots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Ingredient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/nutrition/categories":{"get":{"tags":["Nutrition"],"summary":"List nutrient categories","description":"Retrieve all hierarchical nutrient categories sorted by display order.","responses":{"200":{"description":"List of nutrient categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/nutrition/nutrients":{"get":{"tags":["Nutrition"],"summary":"List all master nutrients","description":"Retrieve standard nutrients master list with advanced search, category, unit, usage filters, sorting, and pagination.","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Page number (default 1)"},"required":false,"description":"Page number (default 1)","name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":500,"description":"Items per page (default 25)"},"required":false,"description":"Items per page (default 25)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Search by display name, code, or synonym alias"},"required":false,"description":"Search by display name, code, or synonym alias","name":"search","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by nutrient category UUID"},"required":false,"description":"Filter by nutrient category UUID","name":"categoryId","in":"query"},{"schema":{"type":"string","description":"Filter by default unit (g, mg, mcg, etc.)"},"required":false,"description":"Filter by default unit (g, mg, mcg, etc.)","name":"unit","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by DV presence"},"required":false,"description":"Filter by DV presence","name":"hasDailyValue","in":"query"},{"schema":{"type":"string","enum":["with_ingredients","unused"],"description":"Filter by ingredient usage"},"required":false,"description":"Filter by ingredient usage","name":"hasUsage","in":"query"},{"schema":{"type":"boolean","nullable":true,"description":"Filter by merge audit history"},"required":false,"description":"Filter by merge audit history","name":"hasMergedHistory","in":"query"},{"schema":{"type":"string","enum":["displayName","code","ingredientCount","dailyValue","createdAt"],"description":"Sort field"},"required":false,"description":"Sort field","name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort order"},"required":false,"description":"Sort order","name":"sortOrder","in":"query"}],"responses":{"200":{"description":"List of nutrients with pagination metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}}}},"post":{"tags":["Nutrition"],"summary":"Create a new nutrient","description":"Add a novel or custom biochemical nutrient with % Daily Value targets and aliases.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNutrientInput"}}}},"responses":{"201":{"description":"Nutrient created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/nutrition/nutrients/{id}":{"get":{"tags":["Nutrition"],"summary":"Get nutrient details by ID","description":"Retrieve full details of a nutrient including category and matched aliases.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Nutrient UUID"},"required":true,"description":"Nutrient UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Nutrient details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Nutrient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"put":{"tags":["Nutrition"],"summary":"Update a nutrient","description":"Update an existing nutrient, unit, % DV target, or ingestion aliases.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Nutrient UUID"},"required":true,"description":"Nutrient UUID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNutrientInput"}}}},"responses":{"200":{"description":"Nutrient updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Nutrient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"delete":{"tags":["Nutrition"],"summary":"Delete a nutrient","description":"Remove a nutrient from the master taxonomy.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Nutrient UUID"},"required":true,"description":"Nutrient UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Nutrient deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Nutrient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/nutrition/nutrients/{id}/ingredients":{"get":{"tags":["Nutrition"],"summary":"Get where-used ingredients for nutrient","description":"Retrieve all active master ingredients containing this nutrient, including exact amounts, units, and basis.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Nutrient UUID"},"required":true,"description":"Nutrient UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Where-used ingredient reverse index data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Nutrient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/nutrition/nutrients/{id}/merge":{"post":{"tags":["Nutrition"],"summary":"Merge nutrient into target canonical nutrient","description":"Deduplicates and merges a source nutrient into a target canonical nutrient, reassigning aliases, migrating ingredient links, recording audit metadata, and removing the source record.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Source Nutrient UUID to be merged and removed"},"required":true,"description":"Source Nutrient UUID to be merged and removed","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeNutrientInput"}}}},"responses":{"200":{"description":"Updated target nutrient details after merge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Nutrient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/allergens":{"get":{"tags":["Allergen"],"summary":"List all allergens taxonomy","description":"Retrieve a list of standard and regulatory allergens with ingredient usage counts and jurisdiction filters.","parameters":[{"schema":{"type":"string","description":"Search by allergen label or code"},"required":false,"description":"Search by allergen label or code","name":"search","in":"query"},{"schema":{"type":"string","description":"Filter by jurisdiction (e.g. US_FDA, EU_FIC, GLOBAL)"},"required":false,"description":"Filter by jurisdiction (e.g. US_FDA, EU_FIC, GLOBAL)","name":"jurisdiction","in":"query"}],"responses":{"200":{"description":"List of allergens retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Allergen"],"summary":"Create a new allergen","description":"Register a new regulatory or custom allergen in the global taxonomy.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAllergenInput"}}}},"responses":{"201":{"description":"Allergen created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/allergens/{id}":{"get":{"tags":["Allergen"],"summary":"Get allergen details by ID","description":"Retrieve details of a single allergen by its UUID.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Allergen UUID"},"required":true,"description":"Allergen UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Allergen details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Allergen not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"put":{"tags":["Allergen"],"summary":"Update an allergen","description":"Update an existing allergen definition by its UUID.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Allergen UUID"},"required":true,"description":"Allergen UUID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAllergenInput"}}}},"responses":{"200":{"description":"Allergen updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Allergen not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"delete":{"tags":["Allergen"],"summary":"Delete an allergen","description":"Remove an allergen definition from the taxonomy registry.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Allergen UUID"},"required":true,"description":"Allergen UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Allergen deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Allergen not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/allergens/{id}/ingredients":{"get":{"tags":["Allergen"],"summary":"Get where-used ingredients for allergen","description":"Retrieve all active master ingredients declaring this allergen, including presence risk levels.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Allergen UUID"},"required":true,"description":"Allergen UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Where-used ingredient reverse index data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Allergen not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/vendors":{"get":{"tags":["Vendors"],"summary":"List and search all vendors","description":"Search and retrieve vendors directory with contact information and ingredient counts.","parameters":[{"schema":{"type":"string","description":"Search by vendor name, code, contact, email or country"},"required":false,"description":"Search by vendor name, code, contact, email or country","name":"search","in":"query"},{"schema":{"type":"string","enum":["active","inactive","pending_approval"],"description":"Filter by status"},"required":false,"description":"Filter by status","name":"status","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Page number"},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Items per page"},"required":false,"description":"Items per page","name":"limit","in":"query"}],"responses":{"200":{"description":"List of vendors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}}}},"post":{"tags":["Vendors"],"summary":"Register new supplier / vendor","description":"Create a verified vendor profile with contact personnel and sourcing details.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendorInput"}}}},"responses":{"201":{"description":"Created vendor profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Conflict / duplicate vendor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/vendors/{id}":{"get":{"tags":["Vendors"],"summary":"Get vendor profile by ID","description":"Retrieve vendor details including contact information and metadata.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Vendor UUID"},"required":true,"description":"Vendor UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Vendor details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"put":{"tags":["Vendors"],"summary":"Update vendor profile","description":"Modify vendor details, contacts, status, or notes.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Vendor UUID"},"required":true,"description":"Vendor UUID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVendorInput"}}}},"responses":{"200":{"description":"Updated vendor profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}},"409":{"description":"Conflict / duplicate vendor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}},"delete":{"tags":["Vendors"],"summary":"Delete vendor record","description":"Delete an existing vendor profile if no active locked contracts prevent deletion.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Vendor UUID"},"required":true,"description":"Vendor UUID","name":"id","in":"path"}],"responses":{"200":{"description":"Vendor deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/vendors/{id}/ingredients":{"get":{"tags":["Vendors"],"summary":"Get all ingredients supplied by a vendor","description":"Retrieve all active and catalog ingredients provided by this vendor.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Vendor UUID"},"required":true,"description":"Vendor UUID","name":"id","in":"path"}],"responses":{"200":{"description":"List of ingredients linked to this vendor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/audit-ledger/metrics":{"get":{"tags":["Audit Ledger"],"summary":"Get overall audit ledger compliance metrics and activity summary","responses":{"200":{"description":"Aggregated audit ledger KPIs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/audit-ledger":{"get":{"tags":["Audit Ledger"],"summary":"List all compliance audit ledger records with multi-dimensional filtering","parameters":[{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"name":"eventCategory","in":"query"},{"schema":{"type":"string"},"required":false,"name":"entityType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"entityId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"action","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"dateFrom","in":"query"},{"schema":{"type":"string"},"required":false,"name":"dateTo","in":"query"}],"responses":{"200":{"description":"Paginated list of system audit ledger entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}}}}},"/api/audit-ledger/{id}":{"get":{"tags":["Audit Ledger"],"summary":"Get detailed audit ledger record by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Detailed system audit log event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/audit-ledger/entity/{entityType}/{entityId}":{"get":{"tags":["Audit Ledger"],"summary":"Get complete chronological audit trail for a specific entity","parameters":[{"schema":{"type":"string"},"required":true,"name":"entityType","in":"path"},{"schema":{"type":"string"},"required":true,"name":"entityId","in":"path"}],"responses":{"200":{"description":"Full audit trail for target entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/products":{"get":{"tags":["Products"],"summary":"List all product briefs in work queue","parameters":[{"schema":{"type":"string"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Products list retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"post":{"tags":["Products"],"summary":"Initiate new product brief and auto-generate formulation v1.0-draft","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductInput"}}}},"responses":{"201":{"description":"Product created with initial v1.0 draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/products/{id}":{"get":{"tags":["Products"],"summary":"Get single product with all formulation versions","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Product details retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Product ID is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/formulations/{versionId}":{"get":{"tags":["Formulations"],"summary":"Get complete formulation workbench state for a version ID","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"responses":{"200":{"description":"Formulation details with actives, inactives, nutrition, and allergens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid version ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Formulation version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/formulations/{versionId}/draft":{"put":{"tags":["Formulations"],"summary":"Save draft changes to an active formulation iteration","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFormulationDraftInput"}}}},"responses":{"200":{"description":"Formulation draft updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error or version is locked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/formulations/{versionId}/live-draft":{"put":{"tags":["Formulations"],"summary":"Save in-memory live draft session into Valkey (Debounced auto-save)","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFormulationDraftInput"}}}},"responses":{"200":{"description":"Live draft persisted in Valkey session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"get":{"tags":["Formulations"],"summary":"Retrieve active Valkey live draft session","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"responses":{"200":{"description":"Live draft session or null if no active session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid version ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/formulations/{versionId}/commit":{"post":{"tags":["Formulations"],"summary":"Milestone Commit: Flush Valkey draft into PostgreSQL and write 21 CFR Part 11 audit log","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"changeReason":{"type":"string","example":"Optimized bio-active dose for label claim target"},"updatedBy":{"type":"string"}}}}}},"responses":{"200":{"description":"Formulation milestone committed and sealed in audit ledger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Error committing formulation draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/formulations/{versionId}/discard":{"post":{"tags":["Formulations"],"summary":"Discard Valkey live draft session and revert to last committed version","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"responses":{"200":{"description":"Live draft session discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Error discarding draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/formulations/{versionId}/lock":{"post":{"tags":["Formulations"],"summary":"Lock formulation version and freeze immutable snapshot","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LockFormulationInput"}}}},"responses":{"200":{"description":"Version locked and snapshot saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Error locking formulation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/formulations/{versionId}/duplicate":{"post":{"tags":["Formulations"],"summary":"Branch/Duplicate formulation into new version iteration (v1.1 or v2.0)","parameters":[{"schema":{"type":"string"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateFormulationInput"}}}},"responses":{"201":{"description":"New formulation iteration created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Error duplicating version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}}}}