{"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":"Production 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":"Operation completed successfully"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Jurisdiction"}},"error":{"nullable":true,"example":null}},"required":["success","status","message","data","error"]},"Jurisdiction":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"shortId":{"type":"string","example":"JUR-000001","description":"System-assigned, immutable short ID"},"code":{"type":"string","example":"US_FDA"},"name":{"type":"string","example":"US Food and Drug Administration (21 CFR)"},"countryCode":{"type":"string","example":"US"},"governingBody":{"type":"string","example":"FDA / USDA"},"defaultServingBasis":{"type":"string","enum":["serving_size","100g","100ml","racc"],"example":"serving_size"},"isActive":{"type":"boolean","default":true},"createdBy":{"type":"string"},"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}},"required":["id","shortId","code","name","countryCode","governingBody","defaultServingBasis"]},"ErrorResponse_400":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":400},"message":{"type":"string","example":"An error occurred"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"CreateJurisdictionInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"HEALTH_CANADA"},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Health Canada Food Directorate"},"countryCode":{"type":"string","default":"CA"},"governingBody":{"type":"string","default":"Health Canada"},"defaultServingBasis":{"type":"string","enum":["serving_size","100g","100ml","racc"],"default":"serving_size"},"isActive":{"type":"boolean","default":true},"metadata":{"nullable":true}},"required":["code","name"]},"CreateCertificationInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"OU_KOSHER"},"name":{"type":"string","minLength":1,"maxLength":200,"example":"OU Kosher"},"certifyingBody":{"type":"string","minLength":1,"example":"Orthodox Union"},"jurisdictionId":{"type":"string","nullable":true,"format":"uuid"},"category":{"$ref":"#/components/schemas/CertificationCategory"},"requiresAllFormulaIngredientsCompliant":{"type":"boolean","default":true},"calculationRule":{"type":"string","enum":["all_or_nothing","mass_percentage","mass_percentage_net","active_potency_threshold"],"default":"all_or_nothing"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CertificationTier"},"default":[]},"description":{"type":"string","nullable":true},"badgeIcon":{"type":"string","nullable":true},"isActive":{"type":"boolean","default":true},"metadata":{"nullable":true}},"required":["code","name","certifyingBody"]},"CertificationCategory":{"type":"string","enum":["organic","gmo_free","religious_dietary","allergen_free","ethical_sustainability","sports_anti_doping","quality_clinical","other"],"default":"religious_dietary"},"CertificationTier":{"type":"object","properties":{"id":{"type":"string","example":"100_percent_organic"},"name":{"type":"string","example":"100% Organic"},"minPercentage":{"type":"number","example":100},"maxNonCompliantPercentage":{"type":"number","example":0},"allowSeal":{"type":"boolean","example":true},"allowFrontPanelClaim":{"type":"boolean","example":true},"labelTemplate":{"type":"string","example":"100% Organic"},"rulesDescription":{"type":"string"}},"required":["id","name","minPercentage","maxNonCompliantPercentage","allowSeal","allowFrontPanelClaim","labelTemplate"]},"CreateNutrientClaimRuleInput":{"type":"object","properties":{"nutrientId":{"type":"string","format":"uuid"},"jurisdictionId":{"type":"string","format":"uuid"},"claimTitle":{"type":"string","minLength":1,"maxLength":200,"example":"Excellent Source of Vitamin C"},"claimType":{"type":"string","enum":["nutrient_content","structure_function","health_claim","comparative"],"default":"nutrient_content"},"operator":{"type":"string","enum":[">=","<=","==",">","<","between"],"default":">="},"conditionBasis":{"type":"string","enum":["percent_daily_value","amount_per_serving","amount_per_100g","amount_per_100ml","percent_ww"],"default":"percent_daily_value"},"targetValue":{"anyOf":[{"type":"number"},{"type":"string"}],"example":20},"targetValueMax":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"unit":{"type":"string","default":"%"},"disclaimerText":{"type":"string","nullable":true},"regulatoryCitation":{"type":"string","nullable":true,"example":"21 CFR §101.54(b)"},"isActive":{"type":"boolean","default":true}},"required":["nutrientId","jurisdictionId","claimTitle","targetValue"]},"CreateIngredientClaimInput":{"type":"object","properties":{"ingredientId":{"type":"string","format":"uuid"},"certificationId":{"type":"string","nullable":true,"format":"uuid"},"jurisdictionId":{"type":"string","nullable":true,"format":"uuid"},"claimTitle":{"type":"string","minLength":1,"maxLength":200,"example":"USDA Organic"},"type":{"type":"string","enum":["certification","origin_claim","free_from","active_potency","ethical_sustainability"],"default":"certification"},"certifyingBody":{"type":"string","nullable":true,"example":"CCOF"},"certificateNumber":{"type":"string","nullable":true},"minThresholdPerServing":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"thresholdUnit":{"type":"string","nullable":true,"example":"mg"},"requiresAllFormulaIngredientsCompliant":{"type":"boolean","default":false},"isVerified":{"type":"boolean","default":true},"expiresAt":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true,"example":"https://ecoagri-food.com/images/certicicate-organic-download.jpg"},"tierId":{"type":"string","nullable":true,"example":"100_percent"},"certifiedContentPercentage":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}],"example":100}},"required":["ingredientId","claimTitle"]},"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":false,"description":"Whether the ingredient is in liquid state"},"isAddedSugarSource":{"type":"boolean","default":false,"example":false,"description":"Whether ingredient is a caloric sweetener (e.g. sugar, honey, syrup)"},"agriculturalExclusion":{"type":"string","enum":["none","water","salt"]},"densityGMl":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}],"example":"1.0320","description":"Density in g/mL at 20°C for volumetric conversions"},"shortId":{"type":"string","example":"ING-000042","description":"System-assigned, immutable short ID shared by all versions of the ingredient"},"internalId":{"type":"string","nullable":true,"example":"ING-2026-0842","description":"Legacy free-text internal ID (read-only; superseded by shortId)"},"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","shortId","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","example":"VND-000001","description":"System-assigned, immutable short ID"},"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","code"]},"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"},"shortId":{"type":"string","example":"CAT-000001","description":"System-assigned, immutable short ID"}},"required":["id","code","label"]},"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"},"shortId":{"type":"string","example":"NUT-000001","description":"System-assigned, immutable short ID"},"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","shortId","code","displayName","categoryId","defaultUnit","dailyValue","needsReview"]},"NutrientCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"shortId":{"type":"string","example":"NCT-000001","description":"System-assigned, immutable short ID"},"code":{"type":"string","example":"macronutrient"},"label":{"type":"string","example":"Macronutrients"},"sortOrder":{"type":"number","example":1}},"required":["id","shortId","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"},"shortId":{"type":"string","example":"ALG-000001","description":"System-assigned, immutable short ID"},"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","shortId","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"]},"CreateIngredientRequest":{"type":"object","properties":{"canonicalName":{"type":"string","minLength":1,"maxLength":300,"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":false},"isAddedSugarSource":{"type":"boolean","default":false,"example":false},"agriculturalExclusion":{"type":"string","enum":["none","water","salt"],"description":"Mark water or salt so organic net-percentage maths excludes it"},"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":"approved","example":"approved"},"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,"maxLength":300,"example":"Pasteurized Whole Milk 3.25% (Updated)"},"categoryId":{"type":"string","format":"uuid"},"vendorId":{"type":"string","nullable":true,"format":"uuid"},"isLiquid":{"type":"boolean"},"isAddedSugarSource":{"type":"boolean"},"agriculturalExclusion":{"type":"string","enum":["none","water","salt"]},"densityGMl":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"status":{"type":"string","enum":["draft","approved","published","archived"]},"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,"maxLength":64,"pattern":"^[A-Za-z0-9_]+$","example":"vitamin_d"},"displayName":{"type":"string","minLength":1,"maxLength":200,"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,"maxLength":64,"pattern":"^[A-Za-z0-9_]+$","example":"vitamin_d"},"displayName":{"type":"string","minLength":1,"maxLength":200,"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,"maxLength":64,"pattern":"^[A-Za-z0-9_]+$","example":"mustard"},"label":{"type":"string","minLength":1,"maxLength":200,"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,"maxLength":64,"pattern":"^[A-Za-z0-9_]+$","example":"mustard"},"label":{"type":"string","minLength":1,"maxLength":200,"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,"maxLength":200,"example":"Kerry Ingredients Inc."},"contactName":{"type":"string","nullable":true,"maxLength":150,"example":"Sarah Jenkins"},"contactEmail":{"type":"string","nullable":true,"format":"email","example":"sarah.j@kerry.com"},"contactPhone":{"type":"string","nullable":true,"maxLength":50,"example":"+1 (555) 234-5678"},"address":{"type":"string","nullable":true,"maxLength":300,"example":"3333 Kerry Way, Beloit, WI 53511"},"country":{"type":"string","nullable":true,"maxLength":100,"example":"United States"},"website":{"type":"string","nullable":true,"maxLength":300,"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,"maxLength":2000,"example":"Primary vendor notes"},"createdBy":{"type":"string","example":"developer"},"metadata":{"nullable":true}},"required":["name"]},"UpdateVendorInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Kerry Ingredients Inc."},"contactName":{"type":"string","nullable":true,"maxLength":150,"example":"Sarah Jenkins"},"contactEmail":{"type":"string","nullable":true,"example":"sarah.j@kerry.com"},"contactPhone":{"type":"string","nullable":true,"maxLength":50,"example":"+1 (555) 234-5678"},"address":{"type":"string","nullable":true,"maxLength":300,"example":"3333 Kerry Way, Beloit, WI 53511"},"country":{"type":"string","nullable":true,"maxLength":100,"example":"United States"},"website":{"type":"string","nullable":true,"maxLength":300,"example":"https://www.kerry.com"},"status":{"type":"string","enum":["active","inactive","pending_approval"],"example":"active","description":"Vendor operational status"},"notes":{"type":"string","nullable":true,"maxLength":2000,"example":"Updated vendor notes"},"updatedBy":{"type":"string","example":"developer"},"metadata":{"nullable":true}}},"CreateProductInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Citrus Energy Focus Sparkling Tonic"},"description":{"type":"string","example":"Clean label functional nootropic beverage"},"categoryId":{"type":"string","format":"uuid","example":"796ef6d5-4bf8-466d-a602-0c9f8df56501"},"targetMarket":{"type":"string","example":"US_FDA"},"targetJurisdictionCodes":{"type":"array","items":{"type":"string"},"example":["US_FDA","EU_EFSA"]},"format":{"type":"string","example":"beverage_rtd"},"servingSize":{"type":"number","minimum":0,"exclusiveMinimum":true,"example":250},"servingUnit":{"type":"string","example":"ml"},"containerNetQuantity":{"type":"number","example":500},"containerNetUnit":{"type":"string","example":"ml"},"servingsPerContainer":{"type":"number","example":2},"householdServingCount":{"type":"number","example":1},"householdServingUnit":{"type":"string","example":"can"},"targetDensityGMl":{"type":"number","minimum":0,"exclusiveMinimum":true,"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"},"source":{"type":"string","enum":["jurisdiction_rule","ingredient_cert","nutrient_db","custom"]},"ruleId":{"type":"string","nullable":true},"ingredientClaimId":{"type":"string","nullable":true},"jurisdictionCode":{"type":"string","nullable":true},"nutrientId":{"type":"string","nullable":true},"nutrientCode":{"type":"string","nullable":true},"nutrientName":{"type":"string","nullable":true},"targetNutrientOrActive":{"type":"string"},"operator":{"type":"string"},"targetNumericValue":{"type":"number","nullable":true},"targetNumericValueMax":{"type":"number","nullable":true},"conditionBasis":{"type":"string","nullable":true,"enum":["percent_daily_value","amount_per_serving","amount_per_100g","amount_per_100ml","percent_ww",null]},"targetUnit":{"type":"string","nullable":true},"targetValue":{"type":"string"},"rationaleOrNotes":{"type":"string"},"status":{"type":"string","enum":["target","formulated","verified","flagged"],"default":"target"}},"required":["type","claimText"]},"UpdateProductInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","nullable":true},"categoryId":{"type":"string","format":"uuid"},"targetMarket":{"type":"string"},"targetJurisdictionCodes":{"type":"array","items":{"type":"string"}},"targetCogsPerUnit":{"type":"number","nullable":true,"minimum":0},"status":{"type":"string","enum":["in_development","active","archived"]},"updatedBy":{"type":"string"}}},"TransitionFormulationVersionStatusInput":{"type":"object","properties":{"status":{"type":"string","enum":["locked","submitted","approved","in_trials","released","needs_revision","rejected","terminated","archived"],"description":"Target lifecycle status for the formulation version"},"reason":{"type":"string","description":"Justification or review comment for status transition"},"actorId":{"type":"string"},"actorName":{"type":"string"},"eSignature":{"$ref":"#/components/schemas/ElectronicSignature"}},"required":["status"]},"ElectronicSignature":{"type":"object","properties":{"signerId":{"type":"string","example":"user_food_sci_01"},"signerName":{"type":"string","example":"Dr. Evelyn Reed"},"meaning":{"type":"string","example":"I review and authorize this formulation for commercial production"},"signatureHash":{"type":"string","example":"sha256:4f5a89b7..."},"timestamp":{"type":"string","format":"date-time"}},"required":["signerName","meaning"]},"ForkDraftInput":{"type":"object","properties":{"userId":{"type":"string","example":"scientist_01"},"userName":{"type":"string","example":"Dr. Aditya"},"variantLabel":{"type":"string","example":"Stevia & Monk Fruit Variant"}},"required":["userId"]},"UpdateDraftSandboxInput":{"type":"object","properties":{"servingSize":{"type":"number","minimum":0,"exclusiveMinimum":true,"example":30},"servingUnit":{"type":"string","example":"g"},"householdServingCount":{"type":"number","example":5},"householdServingUnit":{"type":"string","example":"squares"},"servingsPerContainer":{"type":"number","example":3},"containerNetQuantity":{"type":"number","minimum":0,"exclusiveMinimum":true,"example":500,"description":"Net contents of the finished container; kept with the draft and copied to the committed version"},"containerNetUnit":{"type":"string","example":"ml"},"densityGMl":{"type":"number","example":1},"variantLabel":{"type":"string","example":"Stevia Reduced Sugar Variant"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FormulationLine"}},"expectedUpdatedAt":{"type":"string","format":"date-time","description":"The updatedAt the client last saw. If the draft has changed since, the save is rejected with 409."}},"required":["lines"]},"FormulationLine":{"type":"object","properties":{"id":{"type":"string"},"ingredientId":{"type":"string","format":"uuid"},"classification":{"type":"string","enum":["active","inactive"]},"quantity":{"type":"number","minimum":0},"unit":{"type":"string"},"percentWW":{"type":"number","minimum":0},"massG":{"type":"number","minimum":0},"overagePercent":{"type":"number","minimum":0,"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"]},"CommitDraftInput":{"type":"object","properties":{"variantLabel":{"type":"string","example":"Stevia 0-Calorie Variant v1.1"},"changeReason":{"type":"string","example":"Replaced high fructose corn syrup with Stevia Extract"},"committedBy":{"type":"string","example":"Dr. Aditya"}}},"RefreshDraftIngredientsInput":{"type":"object","properties":{"ingredientIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Pinned ingredient version ids to move to their latest version. Omit to refresh every outdated line."}}},"SaveDraftPreparatoryDocInput":{"type":"object","properties":{"preparatoryDoc":{"nullable":true,"description":"Preparatory document structure conforming to PreparatoryDocSchema"},"expectedUpdatedAt":{"type":"string","format":"date-time","description":"The updatedAt the client last saw for optimistic concurrency check."}}},"ImportSourceInput":{"type":"object","properties":{"sourceVersionId":{"type":"string","format":"uuid","description":"UUID of approved formulation version to import from"},"sourceDraftId":{"type":"string","format":"uuid","description":"UUID of draft sandbox to import from"}}},"ApproveFormulationInput":{"type":"object","properties":{"reviewerId":{"type":"string","example":"user-sci-01","description":"Reviewer identifier"},"reviewerName":{"type":"string","minLength":1,"example":"Dr. Evelyn Reed","description":"Display name of reviewer"},"verdict":{"type":"string","enum":["approved","rejected"],"example":"approved","description":"Approval decision"},"rejectionReason":{"type":"string","example":"High moisture content exceeds stability threshold","description":"Required if verdict is rejected"},"comments":{"type":"string","example":"Ready for benchtop trial with 2.5kg pilot batch."},"eSignature":{"type":"object","properties":{"intent":{"type":"string","example":"Formulation approved for prototype testing"},"signedAt":{"type":"string","example":"2026-10-12T15:30:00.000Z"},"authFactorToken":{"type":"string"}}}},"required":["reviewerName","verdict"]},"CreateBatchInput":{"type":"object","properties":{"formulationVersionId":{"type":"string","format":"uuid","description":"Target approved formulation version UUID"},"batchType":{"type":"string","enum":["benchtop","pilot","stability","consumer_test","lab_sample"],"default":"benchtop","example":"benchtop"},"targetBatchSize":{"type":"number","minimum":0,"exclusiveMinimum":true,"example":2.5,"description":"Target mass/volume to produce in pilot laboratory"},"batchUnit":{"type":"string","enum":["kg","g","l","ml"],"default":"kg","example":"kg"},"storageCondition":{"type":"string","enum":["ambient_25c","refrigerated_4c","frozen_minus_18c","incubator_37c_75rh","custom"],"default":"refrigerated_4c","example":"refrigerated_4c"},"storageLocation":{"type":"string","example":"Walk-in Cooler 2, Shelf B"},"targetExpiryDate":{"type":"string","example":"2026-11-12T00:00:00.000Z"},"leadScientistId":{"type":"string","example":"developer"},"leadScientistName":{"type":"string","example":"Lead Formulation Scientist"},"trialObjective":{"type":"string","example":"Validate emulsification and mouthfeel at 2.5kg scale"}},"required":["formulationVersionId","targetBatchSize"]},"UpdateCookingStepInput":{"type":"object","properties":{"status":{"type":"string","enum":["pending","in_progress","completed","skipped"]},"actualTemperatureC":{"type":"number","minimum":-100,"maximum":1000,"example":82.5},"actualDurationSeconds":{"type":"integer","minimum":0,"maximum":31536000,"example":620},"equipmentName":{"type":"string","example":"Silverson High Shear L5M"},"skipReason":{"type":"string","example":"Pre-mix already performed by vendor"},"ingredientsAdded":{"type":"array","items":{"type":"object","properties":{"ingredientId":{"type":"string"},"ingredientName":{"type":"string"},"actualMassG":{"type":"number"},"lotNumber":{"type":"string"}},"required":["ingredientId","ingredientName","actualMassG"]}},"notes":{"type":"string"},"partGroup":{"type":"string"},"siftMeshSize":{"type":"string"},"performedBy":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"intermediateMassG":{"anyOf":[{"type":"number"},{"type":"string"}]},"criteriaResults":{"type":"array","items":{"type":"object","properties":{"criterionId":{"type":"string","minLength":1},"value":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"boolean"},{"nullable":true}]},"verdict":{"type":"string","enum":["pass","fail"],"description":"Operator's pass/fail; required for text criteria"},"note":{"type":"string","nullable":true}},"required":["criterionId"]},"description":"Results for the step's acceptance criteria; judged on the server"},"deviationNote":{"type":"string","nullable":true,"description":"Required to complete a step with an out-of-spec result"}}},"AddCookingStepInput":{"type":"object","properties":{"title":{"type":"string","example":"Phase C: Flavor Oil Addition"},"instruction":{"type":"string","example":"Gently fold in natural lemon extract under low agitation"},"stepOrder":{"type":"integer"},"targetDurationSeconds":{"type":"integer"},"targetTemperatureC":{"type":"number"},"equipmentName":{"type":"string"},"partGroup":{"type":"string"},"siftMeshSize":{"type":"string"},"ingredientsAdded":{"type":"array","items":{"nullable":true}}},"required":["title","instruction"]},"CreateObservationInput":{"type":"object","properties":{"stage":{"type":"string","enum":["during_cooking","immediate_post_cooking","multi_day_stability"],"example":"during_cooking"},"observationDay":{"type":"integer","default":0,"example":0,"description":"0 for trial execution day, 1 for Day 1, etc."},"stepId":{"type":"string","format":"uuid","description":"Optional link to specific unit operation step"},"notesText":{"type":"string","example":"Uniform slurry achieved; no starch agglomeration."},"voiceTranscription":{"type":"string","example":"Aroma is pleasant with citrus notes coming through strongly."},"appearanceScore":{"type":"number","minimum":1,"maximum":5,"example":4.5},"textureScore":{"type":"number","minimum":1,"maximum":5,"example":4},"aromaScore":{"type":"number","minimum":1,"maximum":5,"example":5},"tasteScore":{"type":"number","minimum":1,"maximum":5,"example":4},"overallScore":{"type":"number","minimum":1,"maximum":5,"example":4.5},"appearanceNotes":{"type":"string"},"textureNotes":{"type":"string"},"aromaNotes":{"type":"string"},"tasteNotes":{"type":"string"},"defects":{"type":"array","items":{"type":"string"},"example":["minor_foaming"]},"ph":{"type":"number","minimum":0,"maximum":14,"example":4.25},"brix":{"type":"number","minimum":0,"maximum":100,"example":12.8},"viscosityCp":{"type":"number","minimum":0,"maximum":1000000000,"example":3200},"customReadings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"value":{"anyOf":[{"type":"number"},{"type":"string"}]},"unit":{"type":"string"},"parameterId":{"type":"string"}},"required":["name","value"]},"example":[{"name":"Water Activity (aw)","value":0.62,"unit":"aw"},{"name":"Hardness","value":140,"unit":"g"}]},"recordedById":{"type":"string"},"recordedByName":{"type":"string"}},"required":["stage"]},"TransitionBatchInput":{"type":"object","properties":{"toStatus":{"type":"string","enum":["scheduled","in_cooking","cooling","monitoring_days","qc_analysis","completed","failed","cancelled"]},"actualYieldMass":{"type":"number","minimum":0,"exclusiveMinimum":true,"example":4.85,"description":"Final mass after cooking/processing"},"verdict":{"type":"string","enum":["pass","fail","inconclusive"],"example":"pass"},"disposition":{"type":"string","enum":["approved_for_scaleup","adjust_formulation","rejected_terminated"],"example":"approved_for_scaleup"},"signatures":{"$ref":"#/components/schemas/BatchSignatures"},"trialConclusion":{"type":"string","example":"Formula validated at 5kg scale; stable viscosity and compliant taste."},"reason":{"type":"string"},"actorId":{"type":"string"},"actorName":{"type":"string"}},"required":["toStatus"]},"BatchSignatures":{"type":"object","properties":{"formulator":{"$ref":"#/components/schemas/ElectronicSignatureRecord"},"qaReviewer":{"$ref":"#/components/schemas/ElectronicSignatureRecord"}},"required":["formulator"]},"ElectronicSignatureRecord":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Dr. Evelyn Reed"},"title":{"type":"string","example":"Senior Food Formulation Scientist"},"signedAt":{"type":"string","example":"2026-10-23T14:30:00.000Z"}},"required":["name","signedAt"]},"TrialRunActionInput":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000,"example":"Thermometer probe failed mid-heat"},"actorName":{"type":"string"}}},"SaveBatchQcAnalysisInput":{"type":"object","properties":{"parameterResults":{"type":"array","items":{"type":"object","properties":{"parameterId":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true}]},"passFail":{"type":"string","enum":["pass","fail"]},"verdict":{"type":"string","enum":["pass","fail","conditional","pending"]},"note":{"type":"string"},"comment":{"type":"string"},"testedValue":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"parameterName":{"type":"string"},"category":{"type":"string"},"required":{"type":"boolean"},"isCritical":{"type":"boolean"},"targetValue":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"minValue":{"type":"number","nullable":true},"maxValue":{"type":"number","nullable":true},"uom":{"type":"string","nullable":true}},"required":["parameterId"]}},"specSnapshot":{"type":"array","items":{"nullable":true}},"overallVerdict":{"type":"string","enum":["pass","conditional","fail"]},"notes":{"type":"string"},"testedBy":{"type":"string"},"testedByName":{"type":"string"},"testedAt":{"type":"string","format":"date-time"}},"required":["parameterResults"]},"CreateEquipmentInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"type":{"$ref":"#/components/schemas/EquipmentType"},"capacityMin":{"type":"string","nullable":true},"capacityMax":{"type":"string","nullable":true},"capacityUnit":{"type":"string","nullable":true},"settingsSchema":{"nullable":true},"readabilityG":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"calibrationDueAt":{"type":"string","nullable":true}},"required":["name","type"]},"EquipmentType":{"type":"string","enum":["blender","mixer","kettle","oven","mould","chiller","homogenizer","scale","ph_meter","refractometer","viscometer","texture_analyzer","other"]},"CreateTestParameterInput":{"type":"object","properties":{"code":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"name":{"type":"string","minLength":1,"maxLength":200},"type":{"$ref":"#/components/schemas/TestParameterType"},"unit":{"type":"string","nullable":true},"defaultMethod":{"type":"string","nullable":true},"resultType":{"$ref":"#/components/schemas/TestParameterResultType"},"decimals":{"type":"number","default":2}},"required":["code","name","type"]},"TestParameterType":{"type":"string","enum":["physical","chemical","biological","sensory"]},"TestParameterResultType":{"type":"string","enum":["numeric","pass_fail","scale_1_5","text"],"default":"numeric"},"CreateOperationTemplateInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"instructionTemplate":{"type":"string","minLength":1},"technicianGuidance":{"type":"string","nullable":true},"defaultEquipmentType":{"type":"string","nullable":true},"defaultEquipmentId":{"type":"string","nullable":true,"format":"uuid"},"defaultSettings":{"nullable":true},"defaultDurationMin":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"defaultTemperatureC":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"productCategory":{"type":"string"},"category":{"type":"string","default":"mixing"},"expectedOutput":{"type":"string","nullable":true},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1},"answerType":{"type":"string","default":"yes_no"},"expectedAnswer":{"type":"string","nullable":true},"required":{"type":"boolean","default":true},"sortOrder":{"type":"number"}},"required":["question"]}},"parameterIds":{"type":"array","items":{"type":"object","properties":{"parameterId":{"type":"string","format":"uuid"},"when":{"type":"string","default":"after"},"required":{"type":"boolean","default":true}},"required":["parameterId"]}}},"required":["code","name","instructionTemplate"]},"CreateRulePackInput":{"type":"object","properties":{"jurisdictionId":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1,"maxLength":64,"example":"US_FDA_P101"},"title":{"type":"string","minLength":1,"maxLength":200,"example":"US FDA 21 CFR Part 101 Rules Pack"},"source":{"type":"string","example":"eCFR 21 CFR Part 101"},"sourceAsOf":{"type":"string","example":"2026-09-22"},"notes":{"type":"string"}},"required":["jurisdictionId","code","title"]},"BulkImportRulesInput":{"type":"object","properties":{"jurisdictionId":{"type":"string","format":"uuid","description":"Target regulatory jurisdiction ID"},"code":{"type":"string","minLength":1,"maxLength":64,"example":"US_FDA_P101"},"title":{"type":"string","minLength":1,"maxLength":200,"example":"US FDA 21 CFR Part 101 Rules Pack"},"source":{"type":"string","example":"eCFR 21 CFR Part 101"},"sourceAsOf":{"type":"string","example":"2026-01-01"},"notes":{"type":"string"},"versionAction":{"type":"string","enum":["auto","next_version","replace_draft","merge_draft"],"default":"auto"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CreateRuleInput"}},"dryRun":{"type":"boolean","default":false}},"required":["jurisdictionId","code","title","rules"]},"CreateRuleInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"NCC_CHOLESTEROL_FREE"},"family":{"type":"string","enum":["nutrient_content_claim","health_claim","other_claim","label_element","fill_of_container","disqualifying_level","mandatory_nutrient"]},"title":{"type":"string","minLength":1,"maxLength":200,"example":"Cholesterol Free"},"terms":{"type":"array","items":{"type":"string"},"default":[]},"basis":{"type":"string","enum":["per_serving","per_racc","per_racc_and_serving","per_100g","per_50g_if_small_racc","not_applicable"],"default":"per_serving"},"evaluation":{"type":"string","enum":["auto","attestation"],"default":"auto"},"appliesWhen":{"nullable":true},"condition":{"nullable":true},"resultValue":{"nullable":true},"outcomePass":{"type":"string","nullable":true},"outcomeFail":{"type":"string","nullable":true},"outcomeNotApplicable":{"type":"string","nullable":true},"outcomeMissingData":{"type":"string","nullable":true},"requiredStatement":{"type":"string","nullable":true},"disclaimer":{"type":"string","nullable":true},"dependsOn":{"type":"array","items":{"type":"string"},"default":[]},"citation":{"type":"object","nullable":true,"properties":{"title":{"type":"string"},"part":{"type":"string"},"section":{"type":"string"},"paragraph":{"type":"string"},"url":{"type":"string"}},"required":["section"]},"sortOrder":{"type":"integer","default":0},"isActive":{"type":"boolean","default":true}},"required":["code","family","title"]},"ImportExcelRulesInput":{"type":"object","properties":{"jurisdictionCode":{"type":"string","description":"Defaults to the default market configured in Settings"},"packTitle":{"type":"string","default":"US FDA 21 CFR Part 101/130 Regulations"},"packCode":{"type":"string","default":"US_FDA_P101_EXCEL"},"filePath":{"type":"string"},"fileBase64":{"type":"string"},"notes":{"type":"string"}}},"SimulateRulesInput":{"type":"object","properties":{"packId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"draftId":{"type":"string","format":"uuid"},"versionId":{"type":"string","format":"uuid"},"facts":{"type":"object","additionalProperties":{"nullable":true}}}},"CreateRaccInput":{"type":"object","properties":{"categoryCode":{"type":"string","minLength":1},"label":{"type":"string","minLength":1,"maxLength":200},"amount":{"anyOf":[{"type":"number"},{"type":"string","minLength":1}]},"unit":{"type":"string","minLength":1},"householdMeasure":{"type":"string"},"isSmall":{"type":"boolean","default":false}},"required":["categoryCode","label","amount","unit"]},"CreateRoundingRuleInput":{"type":"object","properties":{"target":{"type":"string","minLength":1,"example":"CALORIES"},"brackets":{"type":"array","items":{"$ref":"#/components/schemas/RoundingBracket"}},"notes":{"type":"string"}},"required":["target","brackets"]},"RoundingBracket":{"type":"object","properties":{"gt":{"type":"number"},"gte":{"type":"number"},"lt":{"type":"number"},"lte":{"type":"number"},"increment":{"type":"number"},"display":{"type":"string"},"ruleNote":{"type":"string"}}},"CreateDailyValueInput":{"type":"object","properties":{"nutrientId":{"type":"string","format":"uuid"},"population":{"type":"string","default":"adult"},"value":{"anyOf":[{"type":"number"},{"type":"string","minLength":1}]},"unit":{"type":"string","minLength":1}},"required":["nutrientId","value","unit"]},"CreateNutritionPanelTemplateInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"US_FDA_BEV_STD_V1"},"name":{"type":"string","minLength":1,"maxLength":200,"example":"US FDA Standard Vertical (Beverages)"},"description":{"type":"string","nullable":true},"jurisdictionId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"categoryId":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440003"},"layoutFormat":{"type":"string","enum":["standard_vertical","dual_column_serving_and_container","dual_column_serving_and_100g","tabular_horizontal","linear","supplement_facts"],"default":"standard_vertical"},"primaryBasis":{"type":"string","enum":["per_serving","per_100g","per_100ml","dual_column"],"default":"per_serving"},"energyDisplay":{"type":"string","enum":["kcal_only","kj_only","both_kj_kcal","both_kcal_kj"],"default":"kcal_only"},"sodiumStyle":{"type":"string","enum":["sodium_mg","salt_g"],"default":"sodium_mg"},"nutrientOrdering":{"type":"array","items":{"$ref":"#/components/schemas/TemplateNutrientConfig"},"default":[]},"roundingRulePackId":{"type":"string","nullable":true,"format":"uuid"},"dailyValuesPackId":{"type":"string","nullable":true,"format":"uuid"},"footnoteText":{"type":"string","nullable":true},"stylingTokens":{"$ref":"#/components/schemas/TemplateStylingTokens"},"isActive":{"type":"boolean","default":true}},"required":["code","name","jurisdictionId","categoryId"]},"TemplateNutrientConfig":{"type":"object","properties":{"nutrientCode":{"type":"string","example":"FAT_TOTAL"},"displayName":{"type":"string","example":"Total Fat"},"unit":{"type":"string","example":"g"},"indentLevel":{"type":"integer","minimum":0,"maximum":3,"default":0},"isBold":{"type":"boolean","default":false},"isItalic":{"type":"boolean","default":false},"isMandatory":{"type":"boolean","default":true},"showPercentDv":{"type":"boolean","default":true},"prefixText":{"type":"string","nullable":true},"suffixText":{"type":"string","nullable":true},"borderTop":{"type":"boolean","nullable":true},"rulePackValidationId":{"type":"string","nullable":true}},"required":["nutrientCode","displayName","unit"]},"TemplateStylingTokens":{"type":"object","properties":{"headerText":{"type":"string","default":"Nutrition Facts","example":"Nutrition Facts"},"subHeaderText":{"type":"string","nullable":true},"showThickCalorieBar":{"type":"boolean","default":true},"fontFamily":{"type":"string","enum":["inter","helvetica","arial","system"],"default":"inter"},"borderWidthPx":{"type":"integer","default":2},"showDailyValueFootnote":{"type":"boolean","default":true},"bilingualEnabled":{"type":"boolean","default":false},"secondaryLanguage":{"type":"string","nullable":true}}},"UpdateNutritionPanelTemplateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","nullable":true},"layoutFormat":{"type":"string","enum":["standard_vertical","dual_column_serving_and_container","dual_column_serving_and_100g","tabular_horizontal","linear","supplement_facts"]},"primaryBasis":{"type":"string","enum":["per_serving","per_100g","per_100ml","dual_column"]},"energyDisplay":{"type":"string","enum":["kcal_only","kj_only","both_kj_kcal","both_kcal_kj"]},"sodiumStyle":{"type":"string","enum":["sodium_mg","salt_g"]},"nutrientOrdering":{"type":"array","items":{"$ref":"#/components/schemas/TemplateNutrientConfig"}},"roundingRulePackId":{"type":"string","nullable":true,"format":"uuid"},"dailyValuesPackId":{"type":"string","nullable":true,"format":"uuid"},"footnoteText":{"type":"string","nullable":true},"stylingTokens":{"$ref":"#/components/schemas/TemplateStylingTokens"},"isActive":{"type":"boolean"}}},"CreateCategoryInput":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9_]+$","example":"electrolyte_shot"},"label":{"type":"string","minLength":1,"maxLength":200,"example":"Electrolyte Shots & Liquids"},"description":{"type":"string","nullable":true},"defaultDeliveryFormat":{"type":"string","default":"general"},"defaultServingSize":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"defaultServingUnit":{"type":"string","default":"g"},"displayOrder":{"type":"integer","default":0},"isActive":{"type":"boolean","default":true},"iconKey":{"type":"string","default":"Coffee"}},"required":["code","label"]},"UpdateCategoryInput":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","nullable":true},"defaultDeliveryFormat":{"type":"string"},"defaultServingSize":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"defaultServingUnit":{"type":"string","nullable":true},"displayOrder":{"type":"integer"},"isActive":{"type":"boolean"},"iconKey":{"type":"string"}}},"PresignUploadRequest":{"type":"object","properties":{"folder":{"type":"string","enum":["specs","coas","certifications","prototypes"],"example":"prototypes"},"filename":{"type":"string","example":"viscosity_trial_cook.mp4"},"mimeType":{"type":"string","example":"video/mp4"}},"required":["folder","filename","mimeType"]},"CreateDocumentRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"example":"Raw Material Specification"},"folder":{"type":"string","default":"general","example":"specs"},"storageKey":{"type":"string","minLength":1,"example":"specs/2026/11/a1b2c3d4_spec.pdf"},"mimeType":{"type":"string","example":"application/pdf"},"fileSize":{"type":"integer","example":45210},"sha256":{"type":"string","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"uploadedBy":{"type":"string","example":"developer"}},"required":["title","storageKey"]},"UpdateOrganizationProfileInput":{"type":"object","properties":{"legalName":{"type":"string","minLength":1,"maxLength":200},"displayName":{"type":"string","nullable":true,"example":"Rambh Foods"},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"stateRegion":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"countryCode":{"type":"string","minLength":2,"maxLength":2,"example":"US"},"contactName":{"type":"string","nullable":true},"contactEmail":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","format":"email"},{"nullable":true}]},"contactPhone":{"type":"string","nullable":true},"website":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","format":"uri"},{"nullable":true}]},"taxId":{"type":"string","nullable":true},"registrations":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationRegistration"}},"logoDocumentKey":{"type":"string","nullable":true},"timezone":{"type":"string","minLength":1,"example":"Asia/Kolkata"},"updatedBy":{"type":"string","nullable":true}}},"OrganizationRegistration":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":200,"example":"FDA Food Facility Registration"},"number":{"type":"string","minLength":1,"example":"12345678901"},"jurisdictionCode":{"type":"string","nullable":true,"example":"US_FDA"}},"required":["label","number"]},"UpdateIdSequenceInput":{"type":"object","properties":{"prefix":{"type":"string","example":"FG","description":"1-10 characters, A-Z and 0-9"},"separator":{"type":"string","enum":["-","_","/",""]},"padding":{"type":"integer","minimum":3,"maximum":10},"includeYear":{"type":"boolean"},"nextValue":{"type":"integer","minimum":1,"description":"Advanced: lowering it needs force=true and must not collide"},"force":{"type":"boolean","description":"Allow lowering nextValue (rejected anyway if it would collide)"},"updatedBy":{"type":"string","nullable":true}}},"PreviewIdSequenceInput":{"type":"object","properties":{"prefix":{"type":"string","example":"FG","description":"1-10 characters, A-Z and 0-9"},"separator":{"type":"string","enum":["-","_","/",""]},"padding":{"type":"integer","minimum":3,"maximum":10},"includeYear":{"type":"boolean"},"nextValue":{"type":"integer","minimum":1,"description":"Advanced: lowering it needs force=true and must not collide"}}},"UpdateRegulatorySettingsInput":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"object","properties":{"jurisdictionId":{"type":"string","format":"uuid"},"defaultRulePackId":{"type":"string","nullable":true,"format":"uuid"}},"required":["jurisdictionId"]},"minItems":1},"defaultJurisdictionId":{"type":"string","format":"uuid"},"updatedBy":{"type":"string","nullable":true}},"required":["enabled","defaultJurisdictionId"]},"RegisterInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@rambh.com"},"password":{"type":"string","minLength":10,"maxLength":128,"example":"SecurePassword123!"},"fullName":{"type":"string","minLength":1,"maxLength":200,"example":"Alice Johnson"},"jobTitle":{"type":"string","nullable":true,"maxLength":200,"example":"Lead Food Scientist"}},"required":["email","password","fullName"]},"VerifyEmailInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@rambh.com"},"code":{"type":"string","minLength":6,"maxLength":6,"example":"123456"}},"required":["email","code"]},"ErrorResponse_429":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":429},"message":{"type":"string","example":"An error occurred"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"ResendOtpInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@rambh.com"},"purpose":{"type":"string","enum":["verify_email","reset_password","invite_accept"],"example":"verify_email"}},"required":["email","purpose"]},"ErrorResponse_401":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":401},"message":{"type":"string","example":"An error occurred"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"ErrorResponse_403":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":403},"message":{"type":"string","example":"An error occurred"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"LoginInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@rambh.com"},"password":{"type":"string","minLength":1,"example":"SecurePassword123!"}},"required":["email","password"]},"ForgotPasswordInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@rambh.com"}},"required":["email"]},"ResetPasswordInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@rambh.com"},"code":{"type":"string","minLength":6,"maxLength":6,"example":"123456"},"newPassword":{"type":"string","minLength":10,"maxLength":128,"example":"NewSecurePassword123!"}},"required":["email","code","newPassword"]},"ChangePasswordInput":{"type":"object","properties":{"currentPassword":{"type":"string","minLength":1},"newPassword":{"type":"string","minLength":10,"maxLength":128}},"required":["currentPassword","newPassword"]},"CreateOrganizationInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"Acme Foods Inc"},"slug":{"type":"string","minLength":3,"maxLength":40,"pattern":"^[a-z0-9-]+$","example":"acme-foods"}},"required":["name"]},"UpdateOrganizationInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"Acme Foods Global"},"slug":{"type":"string","minLength":3,"maxLength":40,"pattern":"^[a-z0-9-]+$","example":"acme-global"}}},"InviteMemberInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@acmefoods.com"},"roleKeys":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"example":["food_scientist"]}},"required":["email","roleKeys"]},"AcceptInvitationInput":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"scientist@acmefoods.com"},"code":{"type":"string","minLength":6,"maxLength":6,"example":"123456"}},"required":["email","code"]},"UpdateMemberRolesInput":{"type":"object","properties":{"roleKeys":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"example":["qa_manager","food_scientist"]}},"required":["roleKeys"]},"OnboardingStepKey":{"type":"string","enum":["organization","markets","id_formats","lab_defaults","team","review"]},"SignaturePolicyStep":{"type":"object","properties":{"stepNo":{"type":"integer","minimum":1},"role":{"type":"string"},"meaning":{"type":"string"},"required":{"type":"boolean"},"canBeSameUserAsStep":{"type":"integer","nullable":true}},"required":["stepNo","role","meaning","required"]},"ErrorResponse_423":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"status":{"type":"number","example":423},"message":{"type":"string","example":"An error occurred"},"data":{"nullable":true,"example":null},"error":{"nullable":true,"example":null}},"required":["success","status","message","data"]},"SignRecordBody":{"type":"object","properties":{"password":{"type":"string","minLength":1},"meaning":{"type":"string","minLength":1},"reason":{"type":"string"},"localOffset":{"type":"string"},"contentPayload":{"nullable":true},"recordVersion":{"type":"string"}},"required":["password","meaning"]},"CreateRevisionBody":{"type":"object","properties":{"version":{"type":"string","minLength":1},"summary":{"type":"string","minLength":1},"reason":{"type":"string","minLength":1},"diff":{"type":"object","additionalProperties":{"nullable":true}}},"required":["version","summary","reason"]},"CreateDeviationInput":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1},"sourceType":{"type":"string","enum":["batch_run","batch_step","qc_result","equipment","document","manual"]},"sourceId":{"type":"string"},"classification":{"type":"string","enum":["minor","major","critical"]},"immediateAction":{"type":"string"},"correctionProposed":{"type":"string"},"ccpLimitBreached":{"type":"boolean"},"impactAssessment":{"type":"array","items":{"$ref":"#/components/schemas/ImpactAssessmentRow"}},"rootCause":{"type":"string"},"capaRequired":{"type":"boolean"},"eventDatetime":{"type":"string"}},"required":["title","description"]},"ImpactAssessmentRow":{"type":"object","properties":{"area":{"type":"string"},"assessment":{"type":"string"},"actionRequired":{"type":"boolean"}},"required":["area","assessment"]},"CreateCapaInput":{"type":"object","properties":{"problemStatement":{"type":"string","minLength":1},"sourceRecords":{"type":"array","items":{"$ref":"#/components/schemas/SourceRecordRef"}},"rootCauseMethod":{"type":"string","enum":["5_why","fishbone","other"]},"rootCause":{"type":"string"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/CapaActionRow"}},"effectivenessCriterion":{"type":"string"},"deviationId":{"type":"string","format":"uuid"},"oosId":{"type":"string","format":"uuid"}},"required":["problemStatement"]},"SourceRecordRef":{"type":"object","properties":{"type":{"type":"string","enum":["deviation","capa","change_request","oos","batch_run","qc_result","formula"]},"id":{"type":"string"},"shortId":{"type":"string"},"note":{"type":"string"}},"required":["type","id"]},"CapaActionRow":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["correction","corrective","preventive"]},"description":{"type":"string"},"owner":{"type":"string"},"dueDate":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","completed","cancelled"]},"completedAt":{"type":"string"}},"required":["type","description","owner","dueDate","status"]},"CreateChangeRequestInput":{"type":"object","properties":{"title":{"type":"string","minLength":1},"reason":{"type":"string","minLength":1},"changeTypes":{"type":"array","items":{"type":"string"}},"sourceRecords":{"type":"array","items":{"$ref":"#/components/schemas/SourceRecordRef"}},"proposedChanges":{"type":"array","items":{"$ref":"#/components/schemas/ProposedChangeRow"}},"impactAssessment":{"type":"array","items":{"$ref":"#/components/schemas/ChangeImpactRow"}},"classification":{"type":"string","enum":["minor","major"]},"customerApprovalRequired":{"type":"boolean"}},"required":["title","reason"]},"ProposedChangeRow":{"type":"object","properties":{"item":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"fromValue":{"type":"string"},"toValue":{"type":"string"},"rationale":{"type":"string"}},"required":["item"]},"ChangeImpactRow":{"type":"object","properties":{"area":{"type":"string"},"impact":{"type":"string"},"action":{"type":"string"}},"required":["area","impact"]},"CreateOosInput":{"type":"object","properties":{"qcResultId":{"type":"string","format":"uuid"},"batchId":{"type":"string","format":"uuid"},"testParameterId":{"type":"string","format":"uuid"},"testName":{"type":"string"},"specification":{"type":"string"},"testParameterName":{"type":"string"},"specificationLimit":{"type":"string"},"reportedResult":{"type":"string","minLength":1},"reportedTo":{"type":"string"},"phase1Checklist":{"type":"array","items":{"$ref":"#/components/schemas/Phase1CheckRow"}}},"required":["reportedResult"]},"Phase1CheckRow":{"type":"object","properties":{"check":{"type":"string"},"finding":{"type":"string"},"assignableCause":{"type":"boolean"}},"required":["check","finding","assignableCause"]}},"parameters":{}},"paths":{"/api/jurisdictions":{"get":{"tags":["Jurisdictions"],"summary":"List all regulatory jurisdictions","description":"Retrieve regulatory authorities and jurisdictions governing formulation compliance.","parameters":[{"schema":{"type":"string","description":"Search by code or name"},"required":false,"description":"Search by code or name","name":"search","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"true = only markets enabled in Settings (for pickers that create new work)"},"required":false,"description":"true = only markets enabled in Settings (for pickers that create new work)","name":"enabledOnly","in":"query"}],"responses":{"200":{"description":"List of regulatory jurisdictions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Jurisdictions"],"summary":"Create regulatory jurisdiction","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJurisdictionInput"}}}},"responses":{"201":{"description":"Jurisdiction created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/jurisdictions/{id}":{"get":{"tags":["Jurisdictions"],"summary":"Get jurisdiction by ID with active rules","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Jurisdiction details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Jurisdiction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"patch":{"tags":["Jurisdictions"],"summary":"Update regulatory jurisdiction","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"HEALTH_CANADA"},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Health Canada Food Directorate"},"countryCode":{"type":"string"},"governingBody":{"type":"string"},"defaultServingBasis":{"type":"string","enum":["serving_size","100g","100ml","racc"]},"isActive":{"type":"boolean"},"metadata":{"nullable":true}}}}}},"responses":{"200":{"description":"Jurisdiction updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Jurisdictions"],"summary":"Delete regulatory jurisdiction","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Jurisdiction deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/certifications":{"get":{"tags":["Certifications"],"summary":"List all master certifications","description":"Retrieve master 3rd-party certification standards (e.g. Organic, Kosher, Non-GMO, Halal).","parameters":[{"schema":{"type":"string","description":"Search by code, name, or certifying body"},"required":false,"description":"Search by code, name, or certifying body","name":"search","in":"query"},{"schema":{"type":"string","description":"Filter by category"},"required":false,"description":"Filter by category","name":"category","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by jurisdiction"},"required":false,"description":"Filter by jurisdiction","name":"jurisdictionId","in":"query"},{"schema":{"type":"string","description":"Filter by jurisdiction code"},"required":false,"description":"Filter by jurisdiction code","name":"jurisdictionCode","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by 100% recipe compliance requirement"},"required":false,"description":"Filter by 100% recipe compliance requirement","name":"requiresAll","in":"query"}],"responses":{"200":{"description":"List of master certifications","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Certifications"],"summary":"Create master certification standard","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCertificationInput"}}}},"responses":{"201":{"description":"Certification standard created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/certifications/{id}":{"get":{"tags":["Certifications"],"summary":"Get master certification by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Certification details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Certification not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"patch":{"tags":["Certifications"],"summary":"Update master certification standard","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"OU_KOSHER"},"name":{"type":"string","minLength":1,"maxLength":200,"example":"OU Kosher"},"certifyingBody":{"type":"string","minLength":1,"example":"Orthodox Union"},"jurisdictionId":{"type":"string","nullable":true,"format":"uuid"},"category":{"$ref":"#/components/schemas/CertificationCategory"},"requiresAllFormulaIngredientsCompliant":{"type":"boolean"},"calculationRule":{"type":"string","enum":["all_or_nothing","mass_percentage","mass_percentage_net","active_potency_threshold"]},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CertificationTier"}},"description":{"type":"string","nullable":true},"badgeIcon":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"metadata":{"nullable":true}}}}}},"responses":{"200":{"description":"Certification standard updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Certifications"],"summary":"Delete master certification standard","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Certification standard deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/compliance/nutrient-claim-rules":{"get":{"tags":["Compliance & Claims"],"summary":"List nutrient claim condition rules","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"nutrientId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"jurisdictionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"claimType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of nutrient claim rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Compliance & Claims"],"summary":"Create a nutrient claim rule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNutrientClaimRuleInput"}}}},"responses":{"201":{"description":"Nutrient claim rule created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/compliance/nutrient-claim-rules/{id}":{"put":{"tags":["Compliance & Claims"],"summary":"Update a nutrient claim rule","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimTitle":{"type":"string","minLength":1,"maxLength":200,"example":"Excellent Source of Vitamin C"},"claimType":{"type":"string","enum":["nutrient_content","structure_function","health_claim","comparative"]},"operator":{"type":"string","enum":[">=","<=","==",">","<","between"]},"conditionBasis":{"type":"string","enum":["percent_daily_value","amount_per_serving","amount_per_100g","amount_per_100ml","percent_ww"]},"targetValue":{"anyOf":[{"type":"number"},{"type":"string"}],"example":20},"targetValueMax":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"unit":{"type":"string"},"disclaimerText":{"type":"string","nullable":true},"regulatoryCitation":{"type":"string","nullable":true,"example":"21 CFR §101.54(b)"},"isActive":{"type":"boolean"},"updatedBy":{"type":"string"}}}}}},"responses":{"200":{"description":"Nutrient claim rule updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Compliance & Claims"],"summary":"Delete nutrient claim rule","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Rule deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/compliance/ingredient-claims":{"get":{"tags":["Compliance & Claims"],"summary":"List ingredient certifications and claims","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"ingredientId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"jurisdictionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of ingredient claims","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Compliance & Claims"],"summary":"Attach certification or claim to ingredient","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIngredientClaimInput"}}}},"responses":{"201":{"description":"Ingredient claim created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/compliance/ingredient-claims/{id}":{"put":{"tags":["Compliance & Claims"],"summary":"Update ingredient claim or certification evidence","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ingredientId":{"type":"string","format":"uuid"},"certificationId":{"type":"string","nullable":true,"format":"uuid"},"jurisdictionId":{"type":"string","nullable":true,"format":"uuid"},"claimTitle":{"type":"string","minLength":1,"maxLength":200,"example":"USDA Organic"},"type":{"type":"string","enum":["certification","origin_claim","free_from","active_potency","ethical_sustainability"]},"certifyingBody":{"type":"string","nullable":true,"example":"CCOF"},"certificateNumber":{"type":"string","nullable":true},"minThresholdPerServing":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"thresholdUnit":{"type":"string","nullable":true,"example":"mg"},"requiresAllFormulaIngredientsCompliant":{"type":"boolean"},"isVerified":{"type":"boolean"},"expiresAt":{"type":"string","nullable":true},"documentUrl":{"type":"string","nullable":true,"example":"https://ecoagri-food.com/images/certicicate-organic-download.jpg"},"tierId":{"type":"string","nullable":true,"example":"100_percent"},"certifiedContentPercentage":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}],"example":100}}}}}},"responses":{"200":{"description":"Ingredient claim updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Compliance & Claims"],"summary":"Delete ingredient claim","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Claim deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/compliance/evaluate-claims":{"post":{"tags":["Compliance & Claims"],"summary":"Evaluate formulation claims dynamically","description":"Pass exactly one of draftId or versionId. The server recalculates the formulation itself, so the result cannot be influenced by client-sent numbers.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string","format":"uuid","description":"Evaluate this draft (server-calculated)"},"versionId":{"type":"string","format":"uuid","description":"Evaluate this committed version (server-calculated)"},"jurisdictionCode":{"type":"string","description":"Defaults to the product's target market"}}}}}},"responses":{"200":{"description":"Evaluation results with qualified and near miss claims","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/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/facets":{"get":{"tags":["Ingredient"],"summary":"Get aggregate counts for ingredient quick filters","description":"Returns accurate library totals for all substances, liquids only, caloric sweeteners, Big 9 allergen free, and COA verified.","responses":{"200":{"description":"Aggregated library facet counts","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","example":"false"},"required":false,"description":"Filter by liquid state","name":"isLiquid","in":"query"},{"schema":{"type":"string","enum":["false","true"],"description":"Filter by caloric sweetener state"},"required":false,"description":"Filter by caloric sweetener state","name":"caloricSweetener","in":"query"},{"schema":{"type":"string","enum":["false","true"],"description":"Filter by allergen-free status (free of major allergens)"},"required":false,"description":"Filter by allergen-free status (free of major allergens)","name":"big9Free","in":"query"},{"schema":{"type":"string","enum":["false","true"],"description":"Filter by COA presence / verification"},"required":false,"description":"Filter by COA presence / verification","name":"hasCoa","in":"query"},{"schema":{"type":"string","enum":["approved","published","draft","archived"],"description":"Filter by lifecycle status","example":"approved"},"required":false,"description":"Filter by lifecycle status","name":"status","in":"query"},{"schema":{"type":"string","enum":["false","true"],"description":"Include past versions and archived items","example":"false"},"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 short ID or legacy internal ID (substring match)"},"required":false,"description":"Filter by short ID or legacy internal ID (substring match)","name":"internalId","in":"query"},{"schema":{"type":"string","description":"Filter by vendor lot #"},"required":false,"description":"Filter by vendor lot #","name":"vendorLotNumber","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter ingredients linking a master certification standard UUID"},"required":false,"description":"Filter ingredients linking a master certification standard UUID","name":"certificationId","in":"query"},{"schema":{"type":"string","description":"Filter ingredients by claim type (certification, origin_claim, free_from, active_potency, ethical_sustainability)"},"required":false,"description":"Filter ingredients by claim type (certification, origin_claim, free_from, active_potency, ethical_sustainability)","name":"claimType","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/ingredients/{id}/latest":{"get":{"tags":["Ingredient"],"summary":"Get the latest version of an ingredient","description":"Resolves any version id (or the stable entity id) to the current version. Drafts use this to offer 'ingredient updated, refresh?'.","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":"The current version of the ingredient","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Ingredient not found or archived","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":"Comma-separated nutrient category codes, e.g. vitamin,mineral"},"required":false,"description":"Comma-separated nutrient category codes, e.g. vitamin,mineral","name":"categoryCodes","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":"string","enum":["true","false"],"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/summary":{"get":{"tags":["Nutrition"],"summary":"Nutrient library summary","description":"Counts over all non-archived nutrients: total, macronutrients, vitamins & minerals, unused, merged.","responses":{"200":{"description":"Nutrient library counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/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":"integer","minimum":1,"default":1,"example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"required":false,"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":"integer","minimum":1,"default":1,"example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"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"}}}}}}},"/api/products/metrics":{"get":{"tags":["Products"],"summary":"Get global product catalog metrics and counts","responses":{"200":{"description":"Product catalog metrics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/products":{"get":{"tags":["Products"],"summary":"List all product briefs in work queue","parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20},"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"}}}}}}},"/api/products/{id}":{"get":{"tags":["Products"],"summary":"Get single product with all formulation versions","parameters":[{"schema":{"type":"string","format":"uuid"},"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"}}}}}},"patch":{"tags":["Products"],"summary":"Update a product brief","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductInput"}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"delete":{"tags":["Products"],"summary":"Archive a product","description":"Products are archived, never deleted, so committed versions and the audit trail stay intact.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Product archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/formulations/{versionId}":{"get":{"tags":["Formulations"],"summary":"Get complete formulation workbench state for a version ID","parameters":[{"schema":{"type":"string","format":"uuid"},"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"}}}}}}},"/api/formulation-versions":{"get":{"tags":["Formulations"],"summary":"List formulation versions with optional filtering (status, product)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"productId","in":"query"},{"schema":{"type":"string","example":"approved","description":"Filter by version status (e.g. approved, submitted, locked)"},"required":false,"description":"Filter by version status (e.g. approved, submitted, locked)","name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Formulation versions list retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/formulation-versions/{versionId}/status":{"patch":{"tags":["Formulations"],"summary":"Transition formulation version lifecycle status (e.g. submitted, in_trials, released, needs_revision)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionFormulationVersionStatusInput"}}}},"responses":{"200":{"description":"Formulation version status updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid status transition request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Formulation version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/products/{productId}/versions/{versionId}/fork-draft":{"post":{"tags":["Formulations"],"summary":"Fork a formulation version into an isolated private draft sandbox","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"productId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForkDraftInput"}}}},"responses":{"201":{"description":"Draft sandbox created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Base 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"}}}}}}},"/api/formulation-drafts/{draftId}":{"get":{"tags":["Formulations"],"summary":"Get complete state of a private formulation draft sandbox","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"responses":{"200":{"description":"Draft sandbox details with live mass balance and dual-basis nutrition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Draft sandbox 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"}}}}}},"put":{"tags":["Formulations"],"summary":"Silent auto-save update for a formulation draft sandbox (no audit noise)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDraftSandboxInput"}}}},"responses":{"200":{"description":"Draft sandbox auto-saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Error auto-saving draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"The draft was changed elsewhere since expectedUpdatedAt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"delete":{"tags":["Formulations"],"summary":"Discard / delete a formulation draft sandbox","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"responses":{"200":{"description":"Draft sandbox deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/products/{productId}/drafts":{"get":{"tags":["Formulations"],"summary":"List all active draft sandboxes for a product","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"productId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"userId","in":"query"}],"responses":{"200":{"description":"Active formulation drafts list","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"}}}}}}},"/api/formulation-drafts/{draftId}/commit":{"post":{"tags":["Formulations"],"summary":"Commit & Publish a formulation draft into a sealed immutable version / variant with 21 CFR Part 11 audit log","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitDraftInput"}}}},"responses":{"201":{"description":"Formulation variant committed and sealed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Mass balance or 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"}}}}}}},"/api/formulation-drafts/{draftId}/refresh-ingredients":{"post":{"tags":["Formulations"],"summary":"Move outdated ingredient lines of a draft to the latest ingredient version","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshDraftIngredientsInput"}}}},"responses":{"200":{"description":"Draft with refreshed ingredient versions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/formulation-drafts/{draftId}/preparatory-doc":{"put":{"tags":["Formulations"],"summary":"Auto-save or update the step-by-step preparatory document SOP and QC reference spec for a draft","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveDraftPreparatoryDocInput"}}}},"responses":{"200":{"description":"Draft preparatory document auto-saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid preparatory document structure or conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Optimistic concurrency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/formulation-drafts/{draftId}/import-formula":{"post":{"tags":["Formulations"],"summary":"Import formula ingredient composition from an existing version or draft into this draft sandbox","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportSourceInput"}}}},"responses":{"200":{"description":"Formula imported successfully into draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Source or target draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/formulation-drafts/{draftId}/import-procedure":{"post":{"tags":["Formulations"],"summary":"Import preparatory procedure steps and QC specs from an existing version or draft, re-mapping ingredient links","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportSourceInput"}}}},"responses":{"200":{"description":"Procedure imported and remapped successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Source or target draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/formulations/{versionId}/approve":{"post":{"tags":["Prototypes & Trials"],"summary":"Approve or reject a formulation version with 21 CFR Part 11 electronic signature","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"versionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveFormulationInput"}}}},"responses":{"200":{"description":"Formulation version approval processed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid input or formulation version not in reviewable state","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"}}}}}}},"/api/prototypes/batches":{"post":{"tags":["Prototypes & Trials"],"summary":"Create a new physical prototype batch from an approved formulation version","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBatchInput"}}}},"responses":{"201":{"description":"Prototype batch created with scaled formulation and unit operation steps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Formulation version not approved or invalid parameters","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"}}}}}},"get":{"tags":["Prototypes & Trials"],"summary":"List prototype batches with optional filtering","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"productId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"formulationVersionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"batchType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of prototype batches retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/prototypes/batches/{batchId}":{"get":{"tags":["Prototypes & Trials"],"summary":"Get complete prototype batch workbench state (scaled recipe, steps, observations)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"responses":{"200":{"description":"Prototype batch details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Prototype batch 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"}}}}}}},"/api/prototypes/batches/{batchId}/steps/{stepId}":{"patch":{"tags":["Prototypes & Trials"],"summary":"Update cooking step progress (duration, measured temperature, status)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"stepId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCookingStepInput"}}}},"responses":{"200":{"description":"Cooking step updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Step or batch 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"}}}}}}},"/api/prototypes/batches/{batchId}/steps":{"post":{"tags":["Prototypes & Trials"],"summary":"Add a custom or ad-hoc cooking step to a batch","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCookingStepInput"}}}},"responses":{"201":{"description":"Cooking step added successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Batch 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"}}}}}}},"/api/prototypes/batches/{batchId}/observations":{"post":{"tags":["Prototypes & Trials"],"summary":"Record multi-stage trial observation (cooking, post-cooking, or multi-day shelf check)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateObservationInput"}}}},"responses":{"201":{"description":"Observation recorded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Batch 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"}}}}}},"get":{"tags":["Prototypes & Trials"],"summary":"List all observations for a prototype batch","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"stage","in":"query"},{"schema":{"type":"string"},"required":false,"name":"day","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"Run number (defaults to the current run)"},"required":false,"description":"Run number (defaults to the current run)","name":"run","in":"query"}],"responses":{"200":{"description":"Observations list retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/prototypes/batches/{batchId}/transition":{"post":{"tags":["Prototypes & Trials"],"summary":"Transition prototype batch lifecycle stage (cooking, cooling, monitoring, completed)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionBatchInput"}}}},"responses":{"200":{"description":"Batch status transitioned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Batch 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"}}}}}}},"/api/prototypes/batches/{batchId}/runs/abort":{"post":{"tags":["Prototypes & Trials"],"summary":"Abort the run in progress (reason required); the trial can then start a new run","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialRunActionInput"}}}},"responses":{"200":{"description":"Updated trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Trial or step not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"422":{"description":"Not allowed in the trial's current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/prototypes/batches/{batchId}/runs/restart":{"post":{"tags":["Prototypes & Trials"],"summary":"Start the next run of an aborted or failed trial with fresh steps from the SOP","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialRunActionInput"}}}},"responses":{"200":{"description":"Updated trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Trial or step not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"422":{"description":"Not allowed in the trial's current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/prototypes/batches/{batchId}/steps/{stepId}/restart":{"post":{"tags":["Prototypes & Trials"],"summary":"Restart a step (reason required); later steps already done are reset too","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"stepId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialRunActionInput"}}}},"responses":{"200":{"description":"Updated trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Trial or step not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"422":{"description":"Not allowed in the trial's current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/prototypes/batches/{batchId}/observations/{observationId}/media":{"post":{"tags":["Prototypes & Trials"],"summary":"Upload photo, video, or voice note attachment for an observation","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"observationId","in":"path"}],"responses":{"201":{"description":"Media uploaded and attached successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid media file or payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Observation 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"}}}}}}},"/api/prototypes/batches/{batchId}/qc-analysis":{"post":{"tags":["Prototypes & Trials"],"summary":"Record or update Quality Control (QC) analysis results against reference specification","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveBatchQcAnalysisInput"}}}},"responses":{"200":{"description":"QC analysis recorded and evaluated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid input or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Prototype batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"get":{"tags":["Prototypes & Trials"],"summary":"Get QC analysis record and reference specification for a prototype batch","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"batchId","in":"path"}],"responses":{"200":{"description":"QC analysis and reference spec retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Prototype batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/lab/equipment":{"get":{"tags":["Lab Library"],"summary":"List lab equipment & instruments","parameters":[{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"activeOnly","in":"query"}],"responses":{"200":{"description":"List of equipment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Lab Library"],"summary":"Create new equipment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEquipmentInput"}}}},"responses":{"201":{"description":"Equipment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"409":{"description":"Code already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/lab/equipment/{id}":{"get":{"tags":["Lab Library"],"summary":"Get equipment details","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Equipment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Equipment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"patch":{"tags":["Lab Library"],"summary":"Update equipment","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"type":{"$ref":"#/components/schemas/EquipmentType"},"capacityMin":{"type":"string","nullable":true},"capacityMax":{"type":"string","nullable":true},"capacityUnit":{"type":"string","nullable":true},"settingsSchema":{"nullable":true},"readabilityG":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"calibrationDueAt":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Equipment updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Lab Library"],"summary":"Archive equipment","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Equipment archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/lab/parameters":{"get":{"tags":["Lab Library"],"summary":"List universe of test parameters","parameters":[{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"activeOnly","in":"query"}],"responses":{"200":{"description":"List of test parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Lab Library"],"summary":"Create test parameter","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestParameterInput"}}}},"responses":{"201":{"description":"Parameter created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/lab/parameters/{id}":{"get":{"tags":["Lab Library"],"summary":"Get parameter details","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Parameter details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Parameter not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"patch":{"tags":["Lab Library"],"summary":"Update test parameter","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$"},"name":{"type":"string","minLength":1,"maxLength":200},"type":{"$ref":"#/components/schemas/TestParameterType"},"unit":{"type":"string","nullable":true},"defaultMethod":{"type":"string","nullable":true},"resultType":{"$ref":"#/components/schemas/TestParameterResultType"},"decimals":{"type":"number"}}}}}},"responses":{"200":{"description":"Parameter updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Lab Library"],"summary":"Archive test parameter","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Parameter archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/lab/operation-templates":{"get":{"tags":["Lab Library"],"summary":"List boilerplate operation templates","parameters":[{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string"},"required":false,"name":"productCategory","in":"query"},{"schema":{"type":"string"},"required":false,"name":"activeOnly","in":"query"}],"responses":{"200":{"description":"List of operation templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Lab Library"],"summary":"Create operation template","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOperationTemplateInput"}}}},"responses":{"201":{"description":"Template created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/lab/operation-templates/{id}":{"get":{"tags":["Lab Library"],"summary":"Get operation template details","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Operation template details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"put":{"tags":["Lab Library"],"summary":"Update operation template","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"instructionTemplate":{"type":"string","minLength":1},"technicianGuidance":{"type":"string","nullable":true},"defaultEquipmentType":{"type":"string","nullable":true},"defaultEquipmentId":{"type":"string","nullable":true,"format":"uuid"},"defaultSettings":{"nullable":true},"defaultDurationMin":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"defaultTemperatureC":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"productCategory":{"type":"string"},"category":{"type":"string"},"expectedOutput":{"type":"string","nullable":true},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1},"answerType":{"type":"string","default":"yes_no"},"expectedAnswer":{"type":"string","nullable":true},"required":{"type":"boolean","default":true},"sortOrder":{"type":"number"}},"required":["question"]}},"parameterIds":{"type":"array","items":{"type":"object","properties":{"parameterId":{"type":"string","format":"uuid"},"when":{"type":"string","default":"after"},"required":{"type":"boolean","default":true}},"required":["parameterId"]}}}}}}},"responses":{"200":{"description":"Operation template updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Lab Library"],"summary":"Archive operation template","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Template archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/lab/settings":{"get":{"tags":["Lab Library"],"summary":"Get lab settings","responses":{"200":{"description":"Lab settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"put":{"tags":["Lab Library"],"summary":"Update lab settings","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"defaultWeighingTolerancePct":{"type":"string"},"roundingMode":{"type":"string"},"defaultScaleReadabilityG":{"type":"string"},"updatedBy":{"type":"string","nullable":true},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}]}}}}}},"responses":{"200":{"description":"Lab settings updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs":{"get":{"tags":["Rules Engine"],"summary":"List all rule packs","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"jurisdictionId","in":"query"},{"schema":{"type":"string","enum":["draft","in_review","published","retired"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of rule packs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Rules Engine"],"summary":"Create a new draft rule pack","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRulePackInput"}}}},"responses":{"201":{"description":"Draft rule pack created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}":{"get":{"tags":["Rules Engine"],"summary":"Get rule pack details with all its rules and reference tables","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"Rule pack details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Rule pack not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/rules/packs/{packId}/clone":{"post":{"tags":["Rules Engine"],"summary":"Clone a published or retired pack into a new draft version","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Cloned rule pack created as draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/publish":{"post":{"tags":["Rules Engine"],"summary":"Publish a draft rule pack, making it active and immutable","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"effectiveFrom":{"type":"string"},"publishedBy":{"type":"string"}}}}}},"responses":{"200":{"description":"Rule pack published successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/bulk-import":{"post":{"tags":["Rules Engine"],"summary":"Bulk import rules from JSON with deterministic versioning and AST validation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkImportRulesInput"}}}},"responses":{"200":{"description":"Bulk import dry-run or update completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"201":{"description":"Rule pack created or new version generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/import-excel":{"post":{"tags":["Rules Engine"],"summary":"Import AST rules from USFDAlabel_rule_engine.xlsx workbook across all 5 sheets","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportExcelRulesInput"}}}},"responses":{"201":{"description":"Rule pack created with imported rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/rules":{"get":{"tags":["Rules Engine"],"summary":"List all rules in a pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"family","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Rules Engine"],"summary":"Add a rule to a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRuleInput"}}}},"responses":{"201":{"description":"Rule added successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/rules/{ruleId}":{"patch":{"tags":["Rules Engine"],"summary":"Update a rule in a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"ruleId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64,"example":"NCC_CHOLESTEROL_FREE"},"family":{"type":"string","enum":["nutrient_content_claim","health_claim","other_claim","label_element","fill_of_container","disqualifying_level","mandatory_nutrient"]},"title":{"type":"string","minLength":1,"maxLength":200,"example":"Cholesterol Free"},"terms":{"type":"array","items":{"type":"string"}},"basis":{"type":"string","enum":["per_serving","per_racc","per_racc_and_serving","per_100g","per_50g_if_small_racc","not_applicable"]},"evaluation":{"type":"string","enum":["auto","attestation"]},"appliesWhen":{"nullable":true},"condition":{"nullable":true},"resultValue":{"nullable":true},"outcomePass":{"type":"string","nullable":true},"outcomeFail":{"type":"string","nullable":true},"outcomeNotApplicable":{"type":"string","nullable":true},"outcomeMissingData":{"type":"string","nullable":true},"requiredStatement":{"type":"string","nullable":true},"disclaimer":{"type":"string","nullable":true},"dependsOn":{"type":"array","items":{"type":"string"}},"citation":{"type":"object","nullable":true,"properties":{"title":{"type":"string"},"part":{"type":"string"},"section":{"type":"string"},"paragraph":{"type":"string"},"url":{"type":"string"}},"required":["section"]},"sortOrder":{"type":"integer"},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Rule updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Rules Engine"],"summary":"Delete a rule from a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"ruleId","in":"path"}],"responses":{"200":{"description":"Rule deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/simulate":{"post":{"tags":["Rules Engine"],"summary":"Simulate a rule pack against arbitrary facts or formulation data","description":"Web recreation of the US FDA spreadsheet calculator. Returns real-time evaluation and trace.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateRulesInput"}}}},"responses":{"200":{"description":"Simulation results with execution trace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/reference-data":{"get":{"tags":["Rules Engine"],"summary":"Get unified reference data for a rule pack (RACC, Rounding, DVs)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"Pack reference data bundle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/racc":{"get":{"tags":["Rules Engine"],"summary":"List RACC entries for a pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"RACC entries list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Rules Engine"],"summary":"Add RACC entry to a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRaccInput"}}}},"responses":{"201":{"description":"RACC entry created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/racc/{raccId}":{"put":{"tags":["Rules Engine"],"summary":"Update RACC entry in a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"raccId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"categoryCode":{"type":"string","minLength":1},"label":{"type":"string","minLength":1,"maxLength":200},"amount":{"anyOf":[{"type":"number"},{"type":"string","minLength":1}]},"unit":{"type":"string","minLength":1},"householdMeasure":{"type":"string"},"isSmall":{"type":"boolean"}}}}}},"responses":{"200":{"description":"RACC entry updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"delete":{"tags":["Rules Engine"],"summary":"Delete RACC entry from a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"raccId","in":"path"}],"responses":{"200":{"description":"RACC entry deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/rounding-rules":{"get":{"tags":["Rules Engine"],"summary":"List 21 CFR 101.9(c) rounding rules for a pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"Rounding rules list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Rules Engine"],"summary":"Upsert a rounding rule for a nutrient target in a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoundingRuleInput"}}}},"responses":{"201":{"description":"Rounding rule created or updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/rounding-rules/{id}":{"delete":{"tags":["Rules Engine"],"summary":"Delete a rounding rule from a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Rounding rule deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/daily-values":{"get":{"tags":["Rules Engine"],"summary":"List population reference daily values for a pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"population","in":"query"}],"responses":{"200":{"description":"Population Daily Values list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Rules Engine"],"summary":"Upsert a reference daily value for a nutrient & population in a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDailyValueInput"}}}},"responses":{"201":{"description":"Daily value created or updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/rules/packs/{packId}/daily-values/{id}":{"delete":{"tags":["Rules Engine"],"summary":"Delete a reference daily value from a draft pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Daily value deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/regulatory/nutrition-templates":{"get":{"tags":["Nutrition Fact Templates"],"summary":"List Nutrition Fact Panel templates","description":"Retrieve all configured Nutrition Fact Panel templates with optional jurisdiction and category filters.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"jurisdictionId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string","enum":["standard_vertical","dual_column_serving_and_container","dual_column_serving_and_100g","tabular_horizontal","linear","supplement_facts"]},"required":false,"name":"layoutFormat","in":"query"},{"schema":{"type":"string","enum":["true","false","all"],"default":"all"},"required":false,"name":"isActive","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of nutrition panel templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Nutrition Fact Templates"],"summary":"Create a new Nutrition Fact Panel template","description":"Creates a template. If isActive is true, atomically deactivates any existing active template for the same (jurisdiction, category) pair.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNutritionPanelTemplateInput"}}}},"responses":{"201":{"description":"Nutrition template created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"409":{"description":"Conflict: code already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/regulatory/nutrition-templates/resolve":{"get":{"tags":["Nutrition Fact Templates"],"summary":"Resolve authoritative active template for jurisdiction and category","description":"Resolves the single active template matching jurisdictionId and categoryId. If category has no custom template, falls back to the jurisdiction's general template.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"jurisdictionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"jurisdictionCode","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"categoryCode","in":"query"}],"responses":{"200":{"description":"Resolved authoritative template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"No active template resolved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/regulatory/nutrition-templates/{id}":{"get":{"tags":["Nutrition Fact Templates"],"summary":"Get Nutrition Fact Panel template by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Nutrition panel template details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"put":{"tags":["Nutrition Fact Templates"],"summary":"Update an existing template","description":"Updates template properties. Activating this template will atomically archive/deactivate any existing active template for that (jurisdiction, category) pair.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNutritionPanelTemplateInput"}}}},"responses":{"200":{"description":"Template updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"delete":{"tags":["Nutrition Fact Templates"],"summary":"Delete or archive template","description":"Safely archives or removes template.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Template removed or archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/regulatory/nutrition-templates/{id}/clone":{"post":{"tags":["Nutrition Fact Templates"],"summary":"Clone template as draft for another category or jurisdiction","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"newCode":{"type":"string","minLength":1,"maxLength":64},"newName":{"type":"string","minLength":1,"maxLength":200},"targetJurisdictionId":{"type":"string","format":"uuid"},"targetCategoryId":{"type":"string","format":"uuid"},"makeActive":{"type":"boolean","default":false}},"required":["newCode","newName"]}}}},"responses":{"201":{"description":"Template cloned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/categories":{"get":{"tags":["Product Categories"],"summary":"List all product categories with template coverage","description":"Retrieve all product manufacturing categories with associated product counts and active jurisdiction template indicators.","parameters":[{"schema":{"type":"string"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["active","inactive","all"],"default":"all"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of product categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"post":{"tags":["Product Categories"],"summary":"Create a new product category","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCategoryInput"}}}},"responses":{"201":{"description":"Category created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"409":{"description":"Code already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/categories/{id}":{"get":{"tags":["Product Categories"],"summary":"Get product category details","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Category details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"put":{"tags":["Product Categories"],"summary":"Update product category","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCategoryInput"}}}},"responses":{"200":{"description":"Category updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}},"delete":{"tags":["Product Categories"],"summary":"Delete product category","description":"Deletes a category if not referenced by any products or templates; otherwise archives it.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Category removed or archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/storage/upload":{"post":{"tags":["Storage & Documents"],"summary":"Upload real document, image, audio, or video file to MinIO S3 object store","description":"Handles multipart file uploads for specs, vendor COAs, quality certificates, and trial batch media with 21 CFR Part 11 SHA-256 tamper-evident integrity hashing.","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Binary file payload"},"folder":{"type":"string","enum":["specs","coas","certifications","prototypes"],"description":"Target storage prefix"},"caption":{"type":"string","description":"Optional caption / description"},"tag":{"type":"string","description":"Optional classification tag"}},"required":["folder"]}}}},"responses":{"201":{"description":"File uploaded and stored in MinIO successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid file MIME type, oversized file, or invalid folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"500":{"description":"Internal storage error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/storage/presign":{"post":{"tags":["Storage & Documents"],"summary":"Generate presigned direct upload URL for large files (videos, high-res audio)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresignUploadRequest"}}}},"responses":{"200":{"description":"Presigned URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid folder or MIME type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/documents":{"post":{"tags":["Storage & Documents"],"summary":"Register an uploaded document in the compliance vault","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDocumentRequest"}}}},"responses":{"201":{"description":"Document registered in vault successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid document metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"get":{"tags":["Storage & Documents"],"summary":"List compliance vault documents with folder and search filters","parameters":[{"schema":{"type":"string","description":"Filter by folder (e.g. specs, coas, certifications)"},"required":false,"description":"Filter by folder (e.g. specs, coas, certifications)","name":"folder","in":"query"},{"schema":{"type":"string","description":"Search by title, shortId, or storage key"},"required":false,"description":"Search by title, shortId, or storage key","name":"search","in":"query"},{"schema":{"type":"string","description":"Whether to include archived documents ('true')"},"required":false,"description":"Whether to include archived documents ('true')","name":"includeArchived","in":"query"}],"responses":{"200":{"description":"List of vault documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/documents/{id}/download":{"get":{"tags":["Storage & Documents"],"summary":"Generate download or stream for vault document","parameters":[{"schema":{"type":"string","description":"Document UUID or shortId"},"required":true,"description":"Document UUID or shortId","name":"id","in":"path"},{"schema":{"type":"string","description":"Redirect directly to file stream ('true')"},"required":false,"description":"Redirect directly to file stream ('true')","name":"redirect","in":"query"}],"responses":{"200":{"description":"Download URL and metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"302":{"description":"Redirect to file download stream"},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/documents/{id}":{"delete":{"tags":["Storage & Documents"],"summary":"Soft-delete / archive a document from the vault","parameters":[{"schema":{"type":"string","description":"Document UUID or shortId"},"required":true,"description":"Document UUID or shortId","name":"id","in":"path"}],"responses":{"200":{"description":"Document archived successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/settings/organization":{"get":{"tags":["Settings"],"summary":"Get the organization profile","responses":{"200":{"description":"Organization profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"patch":{"tags":["Settings"],"summary":"Update the organization profile","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationProfileInput"}}}},"responses":{"200":{"description":"Organization profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/id-sequences":{"get":{"tags":["Settings"],"summary":"List the ID format of every record type, with the next ID preview","responses":{"200":{"description":"ID sequences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/settings/id-sequences/{entityKey}":{"patch":{"tags":["Settings"],"summary":"Change the prefix, separator, digits, year segment or counter of one record type","description":"Only records created afterwards are affected; existing short IDs are never rewritten. Numbering continues across a prefix change.","parameters":[{"schema":{"type":"string","example":"product","description":"Record type key (see GET /api/settings/id-sequences)"},"required":true,"description":"Record type key (see GET /api/settings/id-sequences)","name":"entityKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIdSequenceInput"}}}},"responses":{"200":{"description":"ID sequence updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/id-sequences/{entityKey}/preview":{"post":{"tags":["Settings"],"summary":"Preview the next ID for unsaved format edits (nothing is saved or incremented)","parameters":[{"schema":{"type":"string","example":"product","description":"Record type key (see GET /api/settings/id-sequences)"},"required":true,"description":"Record type key (see GET /api/settings/id-sequences)","name":"entityKey","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewIdSequenceInput"}}}},"responses":{"200":{"description":"Preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/regulatory":{"get":{"tags":["Settings"],"summary":"Enabled markets, available markets and published rule packs","responses":{"200":{"description":"Regulatory settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"put":{"tags":["Settings"],"summary":"Replace the enabled markets, the default market and the default rule pack per market","description":"Removing a market that products still target is allowed; the response lists them in `warnings`. Those products keep the market.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRegulatorySettingsInput"}}}},"responses":{"200":{"description":"Regulatory settings updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/lab":{"get":{"tags":["Settings"],"summary":"Get lab settings (moved here; /api/lab/settings keeps working until the frontend switches)","responses":{"200":{"description":"Lab settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}},"patch":{"tags":["Settings"],"summary":"Update lab settings","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"defaultWeighingTolerancePct":{"type":"string"},"roundingMode":{"type":"string"},"defaultScaleReadabilityG":{"type":"string"},"updatedBy":{"type":"string","nullable":true},"updatedAt":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}]}}}}}},"responses":{"200":{"description":"Lab settings updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/auth/register":{"post":{"tags":["Auth"],"summary":"Register new user account","description":"Creates an account with pending_verification status and generates an email verification OTP.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterInput"}}}},"responses":{"201":{"description":"User registered; verification code issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error or password policy violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Account with email already exists and is active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/auth/verify-email":{"post":{"tags":["Auth"],"summary":"Verify user email and start authenticated session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailInput"}}}},"responses":{"200":{"description":"Email verified successfully; sets refresh cookie and returns access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid or expired verification code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/auth/resend-otp":{"post":{"tags":["Auth"],"summary":"Resend verification code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendOtpInput"}}}},"responses":{"200":{"description":"Code resent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"429":{"description":"Rate limit or cooldown active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_429"}}}}}}},"/api/auth/login":{"post":{"tags":["Auth"],"summary":"Sign in with email and password","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginInput"}}}},"responses":{"200":{"description":"Authentication successful; sets refresh cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Email not verified (EMAIL_NOT_VERIFIED) or suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"429":{"description":"Account locked after 5 failed attempts (code ACCOUNT_LOCKED, with lockedUntil and retryAfterSec; Retry-After header). A password reset unlocks it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_429"}}}}}}},"/api/auth/refresh":{"post":{"tags":["Auth"],"summary":"Refresh access token and rotate session","responses":{"200":{"description":"Session refreshed; new access token returned and cookie rotated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Invalid, expired, or reused refresh token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"409":{"description":"Another request refreshed this session a moment ago (code SESSION_REFRESHED); the cookie is kept, retry once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/auth/logout":{"post":{"tags":["Auth"],"summary":"Sign out and revoke active session","responses":{"200":{"description":"Session revoked and cookie cleared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}}}}},"/api/auth/logout-all":{"post":{"tags":["Auth"],"summary":"Sign out and revoke all sessions for authenticated user","responses":{"200":{"description":"All user sessions revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/auth/forgot-password":{"post":{"tags":["Auth"],"summary":"Request password reset code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgotPasswordInput"}}}},"responses":{"200":{"description":"Generic acknowledgement; OTP issued if account exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/auth/reset-password":{"post":{"tags":["Auth"],"summary":"Reset password with one-time verification code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordInput"}}}},"responses":{"200":{"description":"Password reset successfully; all active sessions revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid code or policy violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/auth/change-password":{"post":{"tags":["Auth"],"summary":"Change password for signed-in user","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordInput"}}}},"responses":{"200":{"description":"Password updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Bad request or wrong current password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/auth/me":{"get":{"tags":["Auth"],"summary":"Get current signed-in user profile, organization memberships and resume pointer","responses":{"200":{"description":"User details and resume state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/organizations":{"post":{"tags":["Organizations"],"summary":"Create a new organization","description":"Creates organization in onboarding state and assigns caller as Admin","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationInput"}}}},"responses":{"201":{"description":"Organization successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"409":{"description":"Slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}},"get":{"tags":["Organizations"],"summary":"List caller organizations","description":"Returns all organizations the authenticated user belongs to","responses":{"200":{"description":"List of organizations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/organizations/current":{"get":{"tags":["Organizations"],"summary":"Get current active organization profile, roles, and permissions","responses":{"200":{"description":"Current organization profile and caller permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden / No active organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}},"patch":{"tags":["Organizations"],"summary":"Update current organization profile","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationInput"}}}},"responses":{"200":{"description":"Updated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"409":{"description":"Slug conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/organizations/current/members":{"get":{"tags":["Organizations"],"summary":"List all members of current organization","responses":{"200":{"description":"List of organization members and invited users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/organizations/current/invitations":{"post":{"tags":["Organizations"],"summary":"Invite a new member to current organization","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMemberInput"}}}},"responses":{"201":{"description":"Invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"409":{"description":"User already member or already invited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/invitations/accept":{"post":{"tags":["Organizations"],"summary":"Accept an organization invitation with OTP code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInvitationInput"}}}},"responses":{"200":{"description":"Invitation accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid code or email mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"404":{"description":"Invitation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/organizations/current/invitations/{id}":{"delete":{"tags":["Organizations"],"summary":"Revoke a pending organization invitation","parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Invitation revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"Invitation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/organizations/current/members/{membershipId}":{"patch":{"tags":["Organizations"],"summary":"Update roles assigned to an organization member","parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"membershipId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberRolesInput"}}}},"responses":{"200":{"description":"Roles updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Bad request (cannot modify own roles)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"Member not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}},"409":{"description":"Conflict (LAST_ADMIN rule violation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}},"delete":{"tags":["Organizations"],"summary":"Remove a member from the organization","parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"membershipId","in":"path"}],"responses":{"200":{"description":"Member removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Bad request (use leave endpoint)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"Member not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}},"409":{"description":"Conflict (LAST_ADMIN rule violation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/organizations/current/leave":{"post":{"tags":["Organizations"],"summary":"Leave current organization","responses":{"200":{"description":"Left organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden / No active organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"409":{"description":"Conflict (cannot leave as last admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/roles":{"get":{"tags":["Roles & Permissions"],"summary":"List all built-in and organization-specific roles","responses":{"200":{"description":"List of roles with granted permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/permissions":{"get":{"tags":["Roles & Permissions"],"summary":"List full permission catalog with descriptions","responses":{"200":{"description":"Permission catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/onboarding":{"get":{"tags":["Onboarding"],"summary":"Get organization onboarding progress and saved settings","description":"Returns step completion statuses, real settings data, and half-filled drafts","responses":{"200":{"description":"Current onboarding state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/onboarding/steps/{key}/draft":{"put":{"tags":["Onboarding"],"summary":"Autosave uncommitted form draft for an onboarding step","parameters":[{"schema":{"$ref":"#/components/schemas/OnboardingStepKey"},"required":true,"name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Draft saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Invalid step key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/onboarding/steps/{key}/complete":{"post":{"tags":["Onboarding"],"summary":"Commit and validate an onboarding step, saving to settings tables","description":"Validates input using existing settings functions, writes to settings tables, and advances currentStep","parameters":[{"schema":{"$ref":"#/components/schemas/OnboardingStepKey"},"required":true,"name":"key","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"responses":{"200":{"description":"Step completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"409":{"description":"Step prerequisites missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/onboarding/steps/{key}/skip":{"post":{"tags":["Onboarding"],"summary":"Skip an optional onboarding step","description":"Records skipped status for optional steps (id_formats, lab_defaults, team)","parameters":[{"schema":{"$ref":"#/components/schemas/OnboardingStepKey"},"required":true,"name":"key","in":"path"}],"responses":{"200":{"description":"Step skipped successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Cannot skip required step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/onboarding/complete":{"post":{"tags":["Onboarding"],"summary":"Finish onboarding and activate organization","description":"Ensures all required steps are completed, sets organization status to active","responses":{"200":{"description":"Onboarding finalized; organization activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"409":{"description":"Required onboarding steps incomplete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/onboarding/options":{"get":{"tags":["Onboarding"],"summary":"Get options, master jurisdictions, and default timezones for onboarding","responses":{"200":{"description":"Onboarding reference options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/signatures/policies":{"get":{"tags":["Signatures & Revisions"],"summary":"List all signature policies for the active organization","responses":{"200":{"description":"List of signature policies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/signatures/policies/{recordType}":{"put":{"tags":["Signatures & Revisions"],"summary":"Update or configure custom signature policy for a record type","parameters":[{"schema":{"type":"string"},"required":true,"name":"recordType","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/SignaturePolicyStep"}}},"required":["steps"]}}}},"responses":{"200":{"description":"Updated signature policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/records/{recordType}/{id}/signatures":{"get":{"tags":["Signatures & Revisions"],"summary":"Get signature status and completed signatures for a controlled record","parameters":[{"schema":{"type":"string"},"required":true,"name":"recordType","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Record signatures and approval status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/records/{recordType}/{id}/sign":{"post":{"tags":["Signatures & Revisions"],"summary":"Sign a controlled record step with 21 CFR Part 11 password re-authentication","parameters":[{"schema":{"type":"string"},"required":true,"name":"recordType","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRecordBody"}}}},"responses":{"200":{"description":"Successfully signed step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Signature mismatch or already approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Password verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Role required or self-approval prohibited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"423":{"description":"Signing locked due to too many failed attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_423"}}}}}}},"/api/records/{recordType}/{id}/revisions":{"get":{"tags":["Signatures & Revisions"],"summary":"List all revision history records for a controlled record","parameters":[{"schema":{"type":"string"},"required":true,"name":"recordType","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of revisions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}},"post":{"tags":["Signatures & Revisions"],"summary":"Create a revision entry with mandatory reason for change","parameters":[{"schema":{"type":"string"},"required":true,"name":"recordType","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRevisionBody"}}}},"responses":{"201":{"description":"Revision created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Missing mandatory reason for change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}}}}},"/api/quality/deviations":{"get":{"tags":["Quality Events"],"summary":"List organization deviations with filters and pagination","parameters":[{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"classification","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sourceType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"page","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of deviations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}},"post":{"tags":["Quality Events"],"summary":"Raise a new quality deviation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeviationInput"}}}},"responses":{"201":{"description":"Deviation raised successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/quality/deviations/{id}":{"get":{"tags":["Quality Events"],"summary":"Get deviation details by ID or shortId","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deviation record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"Deviation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/quality/deviations/{id}/close":{"post":{"tags":["Quality Events"],"summary":"Close a deviation with QA sign-off","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deviation closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"409":{"description":"Missing required CAPA link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/quality/capas":{"get":{"tags":["Quality Events"],"summary":"List organization CAPAs with filters","parameters":[{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"page","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of CAPAs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}},"post":{"tags":["Quality Events"],"summary":"Raise a new Corrective and Preventive Action (CAPA)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCapaInput"}}}},"responses":{"201":{"description":"CAPA raised successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/quality/capas/{id}":{"get":{"tags":["Quality Events"],"summary":"Get CAPA details by ID or shortId","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"CAPA record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"CAPA not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/quality/capas/{id}/close":{"post":{"tags":["Quality Events"],"summary":"Close a CAPA after effectiveness verification","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"CAPA closed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"409":{"description":"Effectiveness check missing or actions incomplete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_409"}}}}}}},"/api/quality/change-requests":{"get":{"tags":["Quality Events"],"summary":"List Change Requests (CCB)","parameters":[{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"classification","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"page","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of change requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}},"post":{"tags":["Quality Events"],"summary":"Raise a new Change Request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChangeRequestInput"}}}},"responses":{"201":{"description":"Change Request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/quality/change-requests/{id}":{"get":{"tags":["Quality Events"],"summary":"Get Change Request details","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Change Request record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"Change Request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/quality/oos":{"get":{"tags":["Quality Events"],"summary":"List Out-of-Specification (OOS) investigations","parameters":[{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"page","in":"query"},{"schema":{"type":"number","nullable":true},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of OOS investigations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_Items"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}},"post":{"tags":["Quality Events"],"summary":"Open a new OOS investigation from analytical test result","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOosInput"}}}},"responses":{"201":{"description":"OOS investigation opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}}}}},"/api/quality/oos/{id}":{"get":{"tags":["Quality Events"],"summary":"Get OOS investigation details","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OOS investigation record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_401"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_403"}}}},"404":{"description":"OOS investigation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_404"}}}}}}},"/api/platform/me":{"get":{"tags":["Platform console"],"summary":"Who am I in the console (404 for non-staff)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/step-up":{"post":{"tags":["Platform console"],"summary":"Re-enter password to unlock the console for 12 hours","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string","minLength":1}},"required":["password"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/overview":{"get":{"tags":["Platform console"],"summary":"Platform overview tiles","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/organizations":{"get":{"tags":["Platform console"],"summary":"List organizations","parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["onboarding","active","suspended","archived"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"step","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/organizations/{orgId}":{"get":{"tags":["Platform console"],"summary":"Organization detail (metadata only)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"orgId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/organizations/{orgId}/usage":{"get":{"tags":["Platform console"],"summary":"Record counts per organization-scoped table","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"orgId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/organizations/{orgId}/events":{"get":{"tags":["Platform console"],"summary":"Platform actions on this organization","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/organizations/{orgId}/{action}":{"post":{"tags":["Platform console"],"summary":"Suspend, reactivate or archive an organization","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"orgId","in":"path"},{"schema":{"type":"string","enum":["suspend","reactivate","archive"]},"required":true,"name":"action","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000}},"required":["reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/organizations/{orgId}/invitations/{membershipId}/revoke":{"post":{"tags":["Platform console"],"summary":"Revoke a pending invitation","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"orgId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"membershipId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/users":{"get":{"tags":["Platform console"],"summary":"List users across organizations","parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["pending_verification","active","suspended"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"locked","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"staff","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/users/{userId}":{"get":{"tags":["Platform console"],"summary":"User detail: memberships and sessions","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/users/{userId}/{action}":{"post":{"tags":["Platform console"],"summary":"Unlock, sign out everywhere, suspend or reactivate a user","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userId","in":"path"},{"schema":{"type":"string","enum":["unlock","sign-out-everywhere","suspend","reactivate"]},"required":true,"name":"action","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/jurisdictions":{"get":{"tags":["Platform console"],"summary":"Jurisdictions with pack and organization counts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"post":{"tags":["Platform console"],"summary":"Create a jurisdiction","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":40,"pattern":"^[A-Za-z0-9_]+$"},"name":{"type":"string","minLength":2,"maxLength":200},"countryCode":{"type":"string","minLength":2,"maxLength":10},"governingBody":{"type":"string","maxLength":200},"defaultServingBasis":{"type":"string","enum":["serving_size","100g","100ml","racc"]},"isActive":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["code","name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/jurisdictions/{id}":{"patch":{"tags":["Platform console"],"summary":"Update a jurisdiction (code is immutable)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string","minLength":2,"maxLength":200},"countryCode":{"type":"string","minLength":2,"maxLength":10},"governingBody":{"type":"string","maxLength":200},"defaultServingBasis":{"type":"string","enum":["serving_size","100g","100ml","racc"]},"isActive":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/jurisdictions/{id}/{action}":{"post":{"tags":["Platform console"],"summary":"Archive or restore a jurisdiction","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["archive","restore"]},"required":true,"name":"action","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000}},"required":["reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs":{"get":{"tags":["Platform console"],"summary":"Platform rule packs","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"jurisdictionId","in":"query"},{"schema":{"type":"string","enum":["draft","in_review","published","retired"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/readiness":{"get":{"tags":["Platform console"],"summary":"Checks a pack must pass before review / publish","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/submit":{"post":{"tags":["Platform console"],"summary":"Submit a draft for review","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/return":{"post":{"tags":["Platform console"],"summary":"Return a pack in review to draft","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000}},"required":["reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/publish":{"post":{"tags":["Platform console"],"summary":"Publish (second person, password, effective date)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string","minLength":1},"effectiveFrom":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":2000}},"required":["password","effectiveFrom"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/retire":{"post":{"tags":["Platform console"],"summary":"Retire a published pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000}},"required":["reason"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/diff":{"get":{"tags":["Platform console"],"summary":"Diff against another version (default: previous)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"against","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/golden-cases":{"get":{"tags":["Platform console"],"summary":"Golden test cases","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"post":{"tags":["Platform console"],"summary":"Add a golden test case","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"facts":{"type":"object","additionalProperties":{"nullable":true}},"expected":{"type":"object","additionalProperties":{"type":"string","enum":["pass","fail","not_applicable","missing_data","attestation_required"]}},"notes":{"type":"string","nullable":true,"maxLength":2000}},"required":["name","facts","expected"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/golden-cases/{caseId}":{"patch":{"tags":["Platform console"],"summary":"Edit a golden test case","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"caseId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"facts":{"type":"object","additionalProperties":{"nullable":true}},"expected":{"type":"object","additionalProperties":{"type":"string","enum":["pass","fail","not_applicable","missing_data","attestation_required"]}},"notes":{"type":"string","nullable":true,"maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"delete":{"tags":["Platform console"],"summary":"Delete a golden test case","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"caseId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/golden-cases/run":{"post":{"tags":["Platform console"],"summary":"Run the golden cases","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/impact":{"post":{"tags":["Platform console"],"summary":"Start an impact preview (counts only)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"get":{"tags":["Platform console"],"summary":"Latest impact preview for the pack","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/rule-packs/{packId}/impact/{runId}":{"get":{"tags":["Platform console"],"summary":"One impact preview","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"packId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/catalogs":{"get":{"tags":["Platform console"],"summary":"Shared reference catalogs with row and usage counts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/support-grants":{"get":{"tags":["Platform console"],"summary":"Support access grants","parameters":[{"schema":{"type":"string","enum":["pending","active","expired","denied","revoked"]},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"organizationId","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"mine","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"post":{"tags":["Platform console"],"summary":"Ask an organization for support access","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["read","read_write"]},"reason":{"type":"string","minLength":1,"maxLength":2000},"hours":{"type":"integer","minimum":1,"maximum":72}},"required":["organizationId","reason","hours"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/support-grants/{grantId}/start":{"post":{"tags":["Platform console"],"summary":"Open the organization under an active grant","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"grantId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/support-grants/{grantId}/withdraw":{"post":{"tags":["Platform console"],"summary":"Give up your own request or grant","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"grantId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/support-session/end":{"post":{"tags":["Platform console"],"summary":"Leave the support session and return to your own workspace","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/staff":{"get":{"tags":["Platform console"],"summary":"Platform staff","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}},"post":{"tags":["Platform console"],"summary":"Add a platform staff member","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["owner","admin","regulatory_editor","regulatory_publisher","support","viewer"]}},"required":["email","role"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/staff/{userId}":{"patch":{"tags":["Platform console"],"summary":"Change a staff member's role","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin","regulatory_editor","regulatory_publisher","support","viewer"]}},"required":["role"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/staff/{userId}/remove":{"post":{"tags":["Platform console"],"summary":"Remove a staff member","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/platform/audit":{"get":{"tags":["Platform console"],"summary":"Platform audit log (JSON or CSV)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"actor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"targetType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"targetId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"organizationId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"action","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","enum":["json","csv"]},"required":false,"name":"format","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Step-up required or role lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found (also returned to non-staff)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/notices":{"get":{"tags":["Notices"],"summary":"Latest notices for the active organization, with read state for the caller","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"No active organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/notices/read-all":{"post":{"tags":["Notices"],"summary":"Mark all of the organization's notices as read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"No active organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/notices/{noticeId}/read":{"post":{"tags":["Notices"],"summary":"Mark one notice as read","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"noticeId","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"No active organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/support-access":{"get":{"tags":["Support access"],"summary":"Support access settings and every request or grant for the organization","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Missing permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Already decided or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/support-access/log":{"get":{"tags":["Support access"],"summary":"What Rambh support viewed or changed, newest first","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"grantId","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Missing permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Already decided or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/support-access/settings":{"put":{"tags":["Support access"],"summary":"Let read-only support access start without asking","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"autoApproveReadOnly":{"type":"boolean"}},"required":["autoApproveReadOnly"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Missing permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Already decided or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/support-access/{grantId}/approve":{"post":{"tags":["Support access"],"summary":"Approve a support access request; the time starts now","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"grantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Missing permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Already decided or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/support-access/{grantId}/deny":{"post":{"tags":["Support access"],"summary":"Deny a support access request","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"grantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Missing permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Already decided or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}},"/api/settings/support-access/{grantId}/revoke":{"post":{"tags":["Support access"],"summary":"End support access now","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"grantId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_Data"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"403":{"description":"Missing permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}},"409":{"description":"Already decided or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse_400"}}}}}}}}}