{"openapi":"3.1.0","info":{"title":"BrewForge API","version":"1.0.0","description":"Public API for BrewForge brewing software","contact":{"name":"BrewForge Support","url":"https://brewforge.sh"}},"servers":[{"url":"https://brewforge.sh","description":"Production"},{"url":"http://localhost:3000","description":"Development"}],"tags":[{"name":"Brews","description":"Brew recipe and batch management"},{"name":"Inventory","description":"Ingredient inventory"},{"name":"Equipment","description":"Equipment profiles"},{"name":"Styles","description":"Beer style profiles"},{"name":"Admin","description":"Admin-only ticket and feedback management"},{"name":"Calculators","description":"Free brewing calculators as GET endpoints: no account, no token, open CORS, 25 requests per 10 minutes per IP"},{"name":"Actions: Getting started","description":"Account, plan, units and enabled features; a map of the other toolsets. Always available. Each action is also an MCP tool of the same name on /api/mcp."},{"name":"Actions: Brewing","description":"Recipes and brews, brew day, fermentation readings, evaluations and devices. Each action is also an MCP tool of the same name on /api/mcp."},{"name":"Actions: Cellar","description":"Cellar vessels, packaging, packaged stock, tap lists and labels. Each action is also an MCP tool of the same name on /api/mcp."},{"name":"Actions: Inventory","description":"Ingredient stock, ingredient catalog, packages, orders and the planner (what am I short of). Each action is also an MCP tool of the same name on /api/mcp."},{"name":"Actions: Setup","description":"Profiles (equipment, mash, water, fermentation), styles, custom fields, preferences, calendar, analysis, calculators, imports and exports. Each action is also an MCP tool of the same name on /api/mcp."},{"name":"Actions: Community","description":"Community feed and profiles, recipe sharing, feedback, support tickets, inbox and changelog. Each action is also an MCP tool of the same name on /api/mcp."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token in format: bfk_<random>. Each operation lists the token scope it requires (the scopes are listed below).\n\n- `read`: Read everything (all areas)\n- `write`: Create, change and delete everything (all areas)\n- `brews:read`: List and view brews\n- `brews:write`: Create, update, delete brews and notes\n- `inventory:read`: List inventory items\n- `inventory:write`: Create, update, delete inventory items\n- `equipment:read`: List equipment profiles\n- `equipment:write`: Create, update, delete equipment profiles\n- `styles:read`: List style profiles\n- `styles:write`: Create, update, delete style profiles\n- `profiles:read`: List mash, fermentation, and water profiles\n- `custom-fields:read`: List custom field definitions\n- `custom-fields:write`: Create, update, delete custom field definitions\n- `profiles:write`: Create, update, delete mash, fermentation, and water profiles\n- `cellar:read`: View cellar, packaged stock, tap lists, and labels\n- `cellar:write`: Manage cellar, packaging, stock, tap lists, and labels\n- `settings:read`: View preferences, imports, calculators, and your data export\n- `settings:write`: Change preferences and undo imports\n- `community:read`: View community, feedback, tickets, inbox, and account overview\n- `community:write`: Post, vote, and reply in community, feedback, and tickets"},"adminApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Admin API Key","description":"Admin API key in format: Authorization: Bearer <ADMIN_API_KEY>"},"oauth2":{"type":"oauth2","description":"OAuth 2.1 for apps the user connects (MCP clients). Discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Public clients with PKCE (S256); `write` includes reading.","flows":{"authorizationCode":{"authorizationUrl":"/api/auth/oauth2/authorize","tokenUrl":"/api/auth/oauth2/token","refreshUrl":"/api/auth/oauth2/token","scopes":{"read":"Read your brewing data","write":"Read and change your brewing data","offline_access":"Get a refresh token"}}}}},"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"totalPages":{"type":"integer","description":"Total number of pages"},"hasMore":{"type":"boolean","description":"Whether more pages exist"}},"required":["page","limit","total","totalPages","hasMore"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Error code","example":"UNAUTHORIZED"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","additionalProperties":{},"description":"Additional error details"}},"required":["code","message"]}},"required":["error"]},"BrewStatus":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"],"description":"Current brew status"},"Fermentable":{"type":"object","properties":{"id":{"type":"string","description":"Fermentable ID"},"name":{"type":"string","example":"Pale Malt 2-Row"},"amount":{"type":"number","description":"Amount in grams (g)","example":4500},"percentage":{"type":["number","null"],"description":"Percentage of grain bill (0-100), used in percentage mode"},"color":{"type":["number","null"],"description":"Color in SRM","example":2},"potential":{"type":["number","null"],"description":"Potential in PPG (points per pound per gallon)","example":37},"type":{"type":["string","null"],"enum":["grain","sugar","extract","adjunct","dry_extract","fruit"],"example":"grain"},"addAt":{"type":["string","null"],"enum":["mash","lauter","boil","fermentation"],"description":"When to add","example":"mash"},"addTime":{"type":["number","null"],"description":"Minutes into boil, or days into fermentation"},"nonFermentable":{"type":["boolean","null"],"description":"Whether yeast cannot ferment this ingredient (e.g. lactose, maltodextrin). Unset = fermentable."},"origin":{"type":["string","null"],"example":"US"},"supplier":{"type":["string","null"],"example":"Briess"}},"required":["id","name","amount"]},"Hop":{"type":"object","properties":{"id":{"type":"string","description":"Hop ID"},"name":{"type":"string","example":"Cascade"},"amount":{"type":"number","description":"Amount in grams (g)","example":28},"alphaAcid":{"type":"number","description":"Alpha acid percentage (%)","example":5.5},"use":{"type":["string","null"],"enum":["mash","first_wort","boil","whirlpool","dry_hop"],"example":"boil"},"time":{"type":["number","null"],"description":"Minutes for boil, days for dry hop. Whirlpool: steep minutes (older hops and imports); addedAtMinute wins","example":60},"addedAtMinute":{"type":["number","null"],"minimum":0,"description":"Whirlpool: minute after flameout the hop goes in; it stays until the hopstand ends","example":10},"form":{"type":["string","null"],"enum":["pellet","whole","cryo","extract"],"example":"pellet"},"temperature":{"type":["number","null"],"description":"Temperature in °C (for whirlpool)"},"origin":{"type":["string","null"],"example":"US"},"supplier":{"type":["string","null"],"example":"YCH Hops"},"dryHopDuration":{"type":["number","null"],"description":"Contact time in days (for dry hop)"},"amountMode":{"type":["string","null"],"enum":["grams","g_per_l"],"description":"Input mode: direct weight or concentration"},"gPerL":{"type":["number","null"],"description":"Grams per liter (when amountMode is g_per_l)"}},"required":["id","name","amount","alphaAcid"]},"Yeast":{"type":"object","properties":{"id":{"type":"string","description":"Yeast ID"},"name":{"type":"string","example":"Safale US-05"},"amount":{"type":["number","null"],"description":"Amount (see amountUnit for unit)"},"amountUnit":{"type":["string","null"],"enum":["g","ml","pkg","cells"],"description":"Unit for amount","example":"pkg"},"attenuation":{"type":["number","null"],"description":"Attenuation percentage (%)","example":75},"type":{"type":["string","null"],"enum":["ale","lager","wheat","wine","champagne","brett","kveik"],"example":"ale"},"form":{"type":["string","null"],"enum":["dry","liquid"],"example":"dry"},"lab":{"type":["string","null"],"description":"Yeast laboratory","example":"Fermentis"},"productId":{"type":["string","null"],"description":"Product code","example":"US-05"},"tempMin":{"type":["number","null"],"description":"Minimum fermentation temp in °C"},"tempMax":{"type":["number","null"],"description":"Maximum fermentation temp in °C"}},"required":["id","name"]},"Misc":{"type":"object","properties":{"id":{"type":"string","description":"Misc ingredient ID"},"name":{"type":"string","example":"Irish Moss"},"amount":{"type":["number","null"],"description":"Amount (see amountUnit for unit)"},"amountUnit":{"type":["string","null"],"enum":["g","ml","tsp","tbsp","each","mg"],"example":"g"},"type":{"type":["string","null"],"enum":["water_agent","fining","flavor","spice","herb","fruit","nutrient","other"],"example":"fining"},"use":{"type":["string","null"],"enum":["mash","boil","whirlpool","primary","secondary","bottling"],"example":"boil"},"time":{"type":["number","null"],"description":"Minutes for mash/boil, days for fermentation"},"supplier":{"type":["string","null"],"description":"Manufacturer/brand"}},"required":["id","name"]},"MashStep":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["infusion","decoction","temperature"]},"targetTemp":{"type":"number","description":"Target temperature in °C"},"duration":{"type":"number","description":"Duration in minutes"},"rampTime":{"type":["number","null"],"description":"Ramp time in minutes"},"waterAmount":{"type":["number","null"],"description":"Water amount in liters (for infusion)"},"decoctionVolume":{"type":["number","null"],"description":"Volume of thick mash to pull in liters (for decoction)"},"decoctionReturnTemp":{"type":["number","null"],"description":"Return temperature in °C (for decoction)"},"decoctionBoilDuration":{"type":["number","null"],"description":"Decoction boil duration in minutes"},"decoctionVolumeLoss":{"type":["number","null"],"description":"Evaporation loss during decoction boil in liters"}},"required":["name","type","targetTemp","duration"]},"MashProfile":{"type":["object","null"],"properties":{"name":{"type":["string","null"]},"grainTemp":{"type":["number","null"],"description":"Grain temperature in °C"},"spargeTemp":{"type":["number","null"],"description":"Sparge water temperature in °C"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/MashStep"}},"sourceProfileId":{"type":"string","description":"Optional source Mash Profile ID for this private Recipe snapshot"},"sourceProfileUpdatedAt":{"type":"string","format":"date-time","description":"Optional source Mash Profile updated-at timestamp captured with this private Recipe snapshot"},"sourceProfileSnapshotFingerprint":{"type":"string","description":"Opaque source Mash Profile baseline used to protect locally edited Recipe snapshots"}}},"FermentationStage":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["primary","secondary","tertiary","cold_crash","conditioning","carbonation"]},"targetTemp":{"type":"number","description":"Target temperature in °C"},"duration":{"type":"number","description":"Duration in days"},"rampTime":{"type":["number","null"],"description":"Ramp time in hours"},"pressure":{"type":["number","null"],"description":"Pressure in PSI (for pressurized fermentation)"},"spundingEnabled":{"type":["boolean","null"],"description":"Whether this is the Recipe snapshot's single Spunding Stage"},"spundingSafetyMarginPoints":{"type":["number","null"],"minimum":0,"description":"Explicit spunding safety margin in SG gravity points (defaults to 4)"}},"required":["name","type","targetTemp","duration"]},"FermentationProfile":{"type":["object","null"],"properties":{"name":{"type":"string"},"stages":{"type":"array","items":{"$ref":"#/components/schemas/FermentationStage"}},"sourceProfileId":{"type":"string","description":"Optional source Fermentation Profile ID for this private Recipe snapshot"},"sourceProfileUpdatedAt":{"type":"string","format":"date-time","description":"Optional source Fermentation Profile updated-at timestamp captured with this private Recipe snapshot"},"sourceProfileSnapshotFingerprint":{"type":"string","description":"Opaque source Fermentation Profile baseline used to protect locally edited Recipe snapshots"}}},"Equipment":{"type":["object","null"],"properties":{"name":{"type":["string","null"]},"batchVolume":{"type":"number","description":"Target volume at the configured reference stage (liters)"},"batchVolumeReference":{"type":"string","enum":["fermenter","kettle"],"description":"Stage at which batch volume is measured; defaults to fermenter for legacy snapshots"},"boilTime":{"type":"number","description":"Boil time in minutes"},"efficiency":{"type":"number","description":"Efficiency percentage"},"efficiencyType":{"type":["string","null"],"enum":["mash","brewhouse"]},"boilOffRate":{"type":["number","null"],"description":"Boil-off rate value; its unit is selected by boilOffRateMode"},"boilOffRateMode":{"type":["string","null"],"enum":["volume","percentage"],"description":"Whether boilOffRate is liters per hour or percent of starting pre-boil volume per hour; missing legacy modes mean liters per hour"},"preBoilVolume":{"type":["number","null"],"description":"Explicit hot pre-boil volume target in liters"},"trubLoss":{"type":["number","null"],"description":"Liters"},"mashTunLoss":{"type":["number","null"]},"fermenterLoss":{"type":["number","null"]},"coolingShrinkage":{"type":["number","null"],"description":"Percentage"},"hopUtilization":{"type":["number","null"],"description":"Multiplier (default 1.0)"},"grainAbsorptionRate":{"type":["number","null"]},"waterToGrainRatio":{"type":["number","null"]}},"required":["batchVolume","boilTime","efficiency"],"description":"Equipment profile"},"Style":{"type":["object","null"],"properties":{"name":{"type":"string"},"category":{"type":["string","null"]},"guidelines":{"type":["string","null"],"example":"BJCP 2021"},"ogMin":{"type":["number","null"]},"ogMax":{"type":["number","null"]},"fgMin":{"type":["number","null"]},"fgMax":{"type":["number","null"]},"ibuMin":{"type":["number","null"]},"ibuMax":{"type":["number","null"]},"srmMin":{"type":["number","null"]},"srmMax":{"type":["number","null"]},"abvMin":{"type":["number","null"]},"abvMax":{"type":["number","null"]}},"required":["name"],"description":"Target beer style"},"WaterProfile":{"type":"object","properties":{"name":{"type":["string","null"]},"calcium":{"type":["number","null"],"description":"ppm"},"magnesium":{"type":["number","null"]},"sodium":{"type":["number","null"]},"chloride":{"type":["number","null"]},"sulfate":{"type":["number","null"]},"bicarbonate":{"type":["number","null"]},"ph":{"type":["number","null"]}}},"WaterAdjustment":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"number"},"unit":{"type":"string","enum":["g","ml"]},"addTo":{"type":"string","enum":["mash","sparge","both"]},"packageIngredientId":{"type":"string"}},"required":["name","amount","unit","addTo"]},"Water":{"type":["object","null"],"properties":{"source":{"$ref":"#/components/schemas/WaterProfile"},"target":{"$ref":"#/components/schemas/WaterProfile"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/WaterAdjustment"}},"saltSplitEnabled":{"type":"boolean","description":"Whether salt additions are split between mash and sparge water"},"mashPh":{"type":["number","null"]},"mashWaterAmount":{"type":["number","null"],"description":"Liters"},"spargeWaterAmount":{"type":["number","null"],"description":"Liters"},"secondSource":{"allOf":[{"$ref":"#/components/schemas/WaterProfile"},{"description":"Second water source for blending"}]},"blendRatio":{"type":["number","null"],"description":"Percentage of primary source (0-100)"}},"description":"Water profile and adjustments"},"CalculatedValues":{"type":["object","null"],"properties":{"og":{"type":["number","null"],"description":"Estimated original gravity","example":1.065},"fg":{"type":["number","null"],"description":"Estimated final gravity","example":1.012},"abv":{"type":["number","null"],"description":"Estimated ABV %","example":6.9},"ibu":{"type":["number","null"],"description":"Estimated IBU","example":65},"srm":{"type":["number","null"],"description":"Estimated color (SRM)","example":8},"batchVolume":{"type":["number","null"],"description":"Batch volume in liters","example":20},"preBoilVolume":{"type":["number","null"],"description":"Pre-boil volume in liters"},"mashWater":{"type":["number","null"],"description":"Mash water in liters, in the equipment profile's water volume mode (see waterVolumeMode), as shown in the app"},"spargeWater":{"type":["number","null"],"description":"Sparge water in liters, in the equipment profile's water volume mode (see waterVolumeMode), as shown in the app"},"waterVolumeMode":{"type":"string","enum":["cold","hot"],"description":"Whether mashWater and spargeWater are cold volumes or hot volumes (cold volume scaled up by the cooling shrinkage), per the equipment profile's water volume display setting","example":"cold"},"strikeTemp":{"type":["number","null"],"description":"Strike water temp in °C"},"boilOffLoss":{"type":["number","null"],"description":"Boil-off loss in liters"},"totalGrainWeight":{"type":["number","null"],"description":"Total grain weight in kg"}},"required":["og","fg","abv","ibu","srm","batchVolume","preBoilVolume","mashWater","spargeWater","waterVolumeMode","strikeTemp","boilOffLoss","totalGrainWeight"],"description":"Calculated values from recipe"},"FermentationReading":{"type":"object","properties":{"id":{"type":"string","description":"Reading ID"},"timestamp":{"type":"string","format":"date-time","description":"When reading was taken"},"gravity":{"type":["number","null"],"description":"Specific gravity reading"},"temperature":{"type":["number","null"],"description":"Temperature in °C"},"ph":{"type":["number","null"],"description":"pH reading"},"pressure":{"type":["number","null"],"description":"Pressure in PSI"},"bubblesPerMinute":{"type":["number","null"],"minimum":0,"description":"Airlock activity in bubbles per minute (e.g. Plaato Airlock)"},"gravityVelocity":{"type":["number","null"],"description":"Gravity change the device reports (e.g. RAPT Pill gravity velocity), in SG points (0.001) per day; negative while gravity drops"},"comment":{"type":["string","null"],"description":"Note about this reading"}},"required":["id","timestamp"]},"Carbonation":{"type":["object","null"],"properties":{"method":{"type":"string","enum":["priming","force_carbonation"]},"targetCo2Volumes":{"type":"number","description":"Volumes of CO2"},"sugarType":{"type":["string","null"],"enum":["table_sugar","corn_sugar","dme","honey"]},"sugarAmount":{"type":["number","null"],"description":"Grams"},"beerTemperature":{"type":["number","null"],"description":"Celsius"},"servingTemperature":{"type":["number","null"]},"targetPressurePsi":{"type":["number","null"]}},"required":["method","targetCo2Volumes"]},"CustomMeasurement":{"type":"object","properties":{"name":{"type":"string","description":"Measurement name"},"value":{"type":"number","description":"Measurement value"},"unit":{"type":"string","description":"Unit of measurement"}},"required":["name","value"]},"CustomFieldValue":{"type":"object","properties":{"fieldId":{"type":"string","description":"Custom field definition ID"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}],"description":"Field value"},"key":{"type":"string","description":"Stable Custom Field integration key"},"name":{"type":"string","description":"Field name (resolved from definition)"},"unit":{"type":"string","description":"Field unit (resolved from definition)"},"fieldType":{"type":"string","description":"Field type (resolved from definition)"}},"required":["fieldId","value"]},"MeasuredValues":{"type":["object","null"],"properties":{"mashPh":{"type":["number","null"],"description":"Measured mash pH"},"strikeWaterTemp":{"type":["number","null"],"description":"Strike water temperature in °C"},"strikeWaterVolume":{"type":["number","null"],"description":"Strike water volume in liters"},"preBoilGravity":{"type":["number","null"],"description":"Measured pre-boil gravity"},"preBoilVolume":{"type":["number","null"],"description":"Measured pre-boil volume (liters)"},"spargeWaterVolume":{"type":["number","null"],"description":"Sparge water volume in liters"},"firstRunningsGravity":{"type":["number","null"],"description":"First runnings gravity (SG)"},"originalGravity":{"type":["number","null"],"description":"Measured OG"},"postBoilVolume":{"type":["number","null"],"description":"Measured post-boil volume"},"fermenterVolume":{"type":["number","null"],"description":"Volume into fermenter"},"boilPh":{"type":["number","null"],"description":"Measured boil pH"},"preDilutionGravity":{"type":["number","null"],"description":"Gravity before adding top-up water"},"preDilutionVolume":{"type":["number","null"],"description":"Volume before adding top-up water (liters)"},"actualBoilTime":{"type":["number","null"],"description":"Actual boil time in minutes"},"pitchingTemp":{"type":["number","null"],"description":"Pitching temperature in °C"},"finalGravity":{"type":["number","null"],"description":"Measured FG"},"fermentationPeakTemp":{"type":["number","null"],"description":"Peak fermentation temp"},"actualAbv":{"type":["number","null"],"description":"Actual ABV calculated from OG/FG"},"attenuation":{"type":["number","null"],"description":"Apparent attenuation %"},"fermentationReadings":{"type":"array","items":{"$ref":"#/components/schemas/FermentationReading"},"description":"Time-series gravity/temp readings"},"carbonation":{"$ref":"#/components/schemas/Carbonation"},"customValues":{"type":"array","items":{"$ref":"#/components/schemas/CustomMeasurement"},"description":"Legacy custom measurements"},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"User-defined custom field values"}},"required":["mashPh","strikeWaterTemp","strikeWaterVolume","preBoilGravity","preBoilVolume","spargeWaterVolume","firstRunningsGravity","originalGravity","postBoilVolume","fermenterVolume","boilPh","preDilutionGravity","preDilutionVolume","actualBoilTime","pitchingTemp","finalGravity","fermentationPeakTemp","actualAbv","attenuation","carbonation"],"description":"Measured values from brew day"},"MissingIngredientPrice":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"amount":{"type":"number"},"unit":{"type":"string"}},"required":["name","type","amount","unit"]},"BrewCost":{"type":["object","null"],"properties":{"fermentables":{"type":"number"},"hops":{"type":"number"},"yeast":{"type":"number"},"misc":{"type":"number"},"total":{"type":"number"},"costPerLiter":{"type":["number","null"]},"costPerBottle":{"type":["number","null"],"description":"Cost per 330ml bottle"},"currency":{"type":["string","null"]},"calculatedAt":{"type":["string","null"],"format":"date-time","description":"When cost was computed"},"missingPrices":{"type":"array","items":{"$ref":"#/components/schemas/MissingIngredientPrice"},"description":"Ingredients without price data"}},"required":["fermentables","hops","yeast","misc","total"],"description":"Ingredient cost breakdown"},"BrewNote":{"type":"object","properties":{"id":{"type":"string","description":"Note ID"},"type":{"type":"string","enum":["observation","issue","adjustment","note","reminder"],"description":"Note type/category"},"content":{"type":"string","description":"Note content"},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"],"description":"Brewing phase when note was added"},"timestamp":{"type":"string","format":"date-time","description":"When the note was created"},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values attached to this note"}},"required":["id","type","content","timestamp"]},"Brew":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"},"name":{"type":"string","example":"American IPA"},"description":{"type":["string","null"],"description":"Brew description"},"brewType":{"type":"string","enum":["all_grain","partial_mash","extract"],"description":"Brewing method"},"status":{"$ref":"#/components/schemas/BrewStatus"},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"User tags"},"batchNumber":{"type":["integer","null"],"description":"Batch number"},"brewDate":{"type":["string","null"],"format":"date-time","description":"Actual brew date"},"plannedBrewDate":{"type":["string","null"],"format":"date-time","description":"Planned brew date"},"conditioningStartDate":{"type":["string","null"],"format":"date-time","description":"When the brew actually moved to conditioning. Set automatically on the status change; beer age counts from it instead of the fermentation schedule."},"readyByDate":{"type":["string","null"],"format":"date-time","description":"Date the beer must be ready (end of conditioning), e.g. for an event. The latest brew day is the fermenting stages plus the recipe's total conditioning days before it."},"readyByNote":{"type":["string","null"],"description":"What the beer is ready for, e.g. \"Christmas party\""},"brewerName":{"type":["string","null"],"description":"Name of the brewer"},"parentBrewId":{"type":["string","null"],"description":"ID of the brew this was forked from"},"recipeGroupId":{"type":["string","null"],"description":"Groups all versions of a recipe together"},"versionNumber":{"type":["integer","null"],"description":"Recipe version iteration (1, 2, 3...)"},"versionBranch":{"type":["integer","null"],"description":"Branch suffix for version collisions (1, 2, 3... → v2.1, v2.2)"},"versionNotes":{"type":["string","null"],"description":"What changed in this version"},"tasteRating":{"type":["number","null"],"description":"Taste rating (0-5)"},"tastingNotes":{"type":["string","null"],"description":"Tasting description"},"packagingDate":{"type":["string","null"],"format":"date-time","description":"When beer was packaged"},"finalVolume":{"type":["number","null"],"description":"Actual packaged volume in liters"},"recipe":{"type":["object","null"],"properties":{"fermentables":{"type":"array","items":{"$ref":"#/components/schemas/Fermentable"}},"hops":{"type":"array","items":{"$ref":"#/components/schemas/Hop"}},"yeasts":{"type":"array","items":{"$ref":"#/components/schemas/Yeast"}},"miscs":{"type":"array","items":{"$ref":"#/components/schemas/Misc"}},"batchVolume":{"type":["number","null"],"description":"Target batch volume in liters (L)"},"boilTime":{"type":["number","null"],"description":"Boil time in minutes"},"efficiency":{"type":["number","null"],"description":"Efficiency percentage (0-100)"},"efficiencyType":{"type":["string","null"],"enum":["mash","brewhouse"],"description":"Efficiency type"},"fermentablesPercentMode":{"type":["boolean","null"],"description":"When true, fermentable amounts are calculated from percentages to hit targetOg"},"targetOg":{"type":["number","null"],"description":"Target OG in SG format (e.g., 1.050)"},"hopsScaleMode":{"type":["boolean","null"],"description":"When true, hop amounts are scaled to hit targetIBU"},"targetIBU":{"type":["number","null"],"description":"Target IBU value"},"fgOverride":{"type":["number","null"],"description":"Override calculated FG with this value (SG format, e.g., 1.012)"},"targetCo2Volumes":{"type":["number","null"],"description":"Target carbonation in volumes of CO2"},"mash":{"$ref":"#/components/schemas/MashProfile"},"fermentation":{"$ref":"#/components/schemas/FermentationProfile"}},"description":"Recipe ingredients"},"equipment":{"$ref":"#/components/schemas/Equipment"},"style":{"$ref":"#/components/schemas/Style"},"mashProfile":{"$ref":"#/components/schemas/MashProfile"},"fermentationProfile":{"$ref":"#/components/schemas/FermentationProfile"},"water":{"$ref":"#/components/schemas/Water"},"calculated":{"$ref":"#/components/schemas/CalculatedValues"},"measured":{"$ref":"#/components/schemas/MeasuredValues"},"cost":{"$ref":"#/components/schemas/BrewCost"},"notes":{"type":"array","items":{"$ref":"#/components/schemas/BrewNote"},"description":"Brew notes"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","name","description","brewType","status","tags","batchNumber","brewDate","plannedBrewDate","conditioningStartDate","readyByDate","readyByNote","brewerName","parentBrewId","recipeGroupId","versionNumber","versionBranch","versionNotes","tasteRating","tastingNotes","packagingDate","finalVolume","recipe","equipment","style","mashProfile","fermentationProfile","water","calculated","measured","cost","createdAt","updatedAt"]},"BrewListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"],"description":"Brew description preview"},"brewType":{"type":"string","enum":["all_grain","partial_mash","extract"]},"status":{"$ref":"#/components/schemas/BrewStatus"},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"User tags"},"batchNumber":{"type":["integer","null"]},"brewDate":{"type":["string","null"],"format":"date-time"},"plannedBrewDate":{"type":["string","null"],"format":"date-time"},"styleName":{"type":["string","null"],"description":"Target beer style name"},"estimatedABV":{"type":["number","null"]},"estimatedIBU":{"type":["number","null"]},"estimatedSRM":{"type":["number","null"],"description":"Estimated color (SRM)"},"tasteRating":{"type":["number","null"],"description":"Taste rating (0-5)"},"recipeGroupId":{"type":["string","null"],"description":"Recipe version group"},"versionNumber":{"type":["integer","null"],"description":"Recipe version number"},"versionBranch":{"type":["integer","null"],"description":"Branch suffix (1, 2, 3...)"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","brewType","status","tags","batchNumber","brewDate","plannedBrewDate","styleName","estimatedABV","estimatedIBU","estimatedSRM","tasteRating","recipeGroupId","versionNumber","versionBranch","createdAt","updatedAt"]},"BrewListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BrewListItem"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"CreateFermentationReading":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When reading was taken"},"gravity":{"type":["number","null"],"description":"Specific gravity reading"},"temperature":{"type":["number","null"],"description":"Temperature in °C"},"ph":{"type":["number","null"],"description":"pH reading"},"pressure":{"type":["number","null"],"description":"Pressure in PSI"},"bubblesPerMinute":{"type":["number","null"],"minimum":0,"description":"Airlock activity in bubbles per minute (e.g. Plaato Airlock)"},"gravityVelocity":{"type":["number","null"],"description":"Gravity change the device reports (e.g. RAPT Pill gravity velocity), in SG points (0.001) per day; negative while gravity drops"},"comment":{"type":["string","null"],"description":"Note about this reading"}},"required":["timestamp"]},"WritableCustomFieldValue":{"type":"object","properties":{"fieldId":{"type":"string","description":"Custom field definition ID"},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}],"description":"Field value"}},"required":["fieldId","value"]},"WritableMeasuredValues":{"type":"object","properties":{"mashPh":{"type":["number","null"]},"strikeWaterTemp":{"type":["number","null"]},"strikeWaterVolume":{"type":["number","null"]},"preBoilGravity":{"type":["number","null"]},"preBoilVolume":{"type":["number","null"]},"spargeWaterVolume":{"type":["number","null"]},"firstRunningsGravity":{"type":["number","null"]},"originalGravity":{"type":["number","null"]},"postBoilVolume":{"type":["number","null"]},"fermenterVolume":{"type":["number","null"]},"boilPh":{"type":["number","null"]},"preDilutionGravity":{"type":["number","null"]},"preDilutionVolume":{"type":["number","null"]},"actualBoilTime":{"type":["number","null"]},"pitchingTemp":{"type":["number","null"]},"finalGravity":{"type":["number","null"]},"fermentationPeakTemp":{"type":["number","null"]},"actualAbv":{"type":["number","null"]},"attenuation":{"type":["number","null"]},"fermentationReadings":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/CreateFermentationReading"},{"type":"object","properties":{"id":{"type":"string","description":"Reading ID (server-generated if omitted)"}}}]},"description":"Fermentation readings (merged by ID)"},"carbonation":{"$ref":"#/components/schemas/Carbonation"},"customValues":{"type":"array","items":{"$ref":"#/components/schemas/CustomMeasurement"}},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/WritableCustomFieldValue"}}},"description":"Brew day measurements"},"CreateBrew":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"My New IPA"},"description":{"type":"string","maxLength":2000},"brewType":{"type":"string","enum":["all_grain","partial_mash","extract"],"default":"all_grain"},"status":{"allOf":[{"$ref":"#/components/schemas/BrewStatus"},{"default":"idea"}]},"tags":{"type":"array","items":{"type":"string"}},"plannedBrewDate":{"type":"string","format":"date-time"},"brewDate":{"type":"string","format":"date-time","description":"Actual brew date"},"conditioningStartDate":{"type":["string","null"],"format":"date-time","description":"Actual conditioning start; overrides the date set automatically when the status changes to conditioning. null clears it (age then follows the fermentation schedule)."},"readyByDate":{"type":["string","null"],"format":"date-time","description":"Date the beer must be ready (end of conditioning). null clears it."},"readyByNote":{"type":["string","null"],"maxLength":120,"description":"What the beer is ready for, e.g. \"Christmas party\". null clears it."},"batchNumber":{"type":"integer","description":"Batch number"},"brewerName":{"type":"string","maxLength":200,"description":"Name of the brewer"},"tasteRating":{"type":"number","minimum":0,"maximum":5,"description":"Taste rating (0-5)"},"tastingNotes":{"type":"string","maxLength":5000,"description":"Tasting description"},"packagingDate":{"type":"string","format":"date-time","description":"When beer was packaged"},"finalVolume":{"type":"number","description":"Actual packaged volume in liters"},"recipe":{"type":"object","properties":{"fermentables":{"type":"array","items":{"$ref":"#/components/schemas/Fermentable"}},"hops":{"type":"array","items":{"$ref":"#/components/schemas/Hop"}},"yeasts":{"type":"array","items":{"$ref":"#/components/schemas/Yeast"}},"miscs":{"type":"array","items":{"$ref":"#/components/schemas/Misc"}},"batchVolume":{"type":["number","null"],"description":"Target batch volume in liters (L)"},"boilTime":{"type":["number","null"],"description":"Boil time in minutes"},"efficiency":{"type":["number","null"],"description":"Efficiency percentage (0-100)"},"efficiencyType":{"type":["string","null"],"enum":["mash","brewhouse"],"description":"Efficiency type"},"fermentablesPercentMode":{"type":["boolean","null"],"description":"When true, fermentable amounts are calculated from percentages to hit targetOg"},"targetOg":{"type":["number","null"],"description":"Target OG in SG format (e.g., 1.050)"},"hopsScaleMode":{"type":["boolean","null"],"description":"When true, hop amounts are scaled to hit targetIBU"},"targetIBU":{"type":["number","null"],"description":"Target IBU value"},"fgOverride":{"type":["number","null"],"description":"Override calculated FG with this value (SG format, e.g., 1.012)"},"targetCo2Volumes":{"type":["number","null"],"description":"Target carbonation in volumes of CO2"},"mash":{"$ref":"#/components/schemas/MashProfile"},"fermentation":{"$ref":"#/components/schemas/FermentationProfile"}}},"equipment":{"allOf":[{"$ref":"#/components/schemas/Equipment"},{"type":"object"}]},"style":{"allOf":[{"$ref":"#/components/schemas/Style"},{"type":"object"}]},"water":{"allOf":[{"$ref":"#/components/schemas/Water"},{"type":"object"}]},"measuredValues":{"$ref":"#/components/schemas/WritableMeasuredValues"}},"required":["name"]},"UpdateBrew":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"My New IPA"},"description":{"type":"string","maxLength":2000},"brewType":{"type":"string","enum":["all_grain","partial_mash","extract"],"default":"all_grain"},"status":{"allOf":[{"$ref":"#/components/schemas/BrewStatus"},{"default":"idea"}]},"tags":{"type":"array","items":{"type":"string"}},"plannedBrewDate":{"type":"string","format":"date-time"},"brewDate":{"type":"string","format":"date-time","description":"Actual brew date"},"conditioningStartDate":{"type":["string","null"],"format":"date-time","description":"Actual conditioning start; overrides the date set automatically when the status changes to conditioning. null clears it (age then follows the fermentation schedule)."},"readyByDate":{"type":["string","null"],"format":"date-time","description":"Date the beer must be ready (end of conditioning). null clears it."},"readyByNote":{"type":["string","null"],"maxLength":120,"description":"What the beer is ready for, e.g. \"Christmas party\". null clears it."},"batchNumber":{"type":"integer","description":"Batch number"},"brewerName":{"type":"string","maxLength":200,"description":"Name of the brewer"},"tasteRating":{"type":"number","minimum":0,"maximum":5,"description":"Taste rating (0-5)"},"tastingNotes":{"type":"string","maxLength":5000,"description":"Tasting description"},"packagingDate":{"type":"string","format":"date-time","description":"When beer was packaged"},"finalVolume":{"type":"number","description":"Actual packaged volume in liters"},"recipe":{"type":"object","properties":{"fermentables":{"type":"array","items":{"$ref":"#/components/schemas/Fermentable"}},"hops":{"type":"array","items":{"$ref":"#/components/schemas/Hop"}},"yeasts":{"type":"array","items":{"$ref":"#/components/schemas/Yeast"}},"miscs":{"type":"array","items":{"$ref":"#/components/schemas/Misc"}},"batchVolume":{"type":["number","null"],"description":"Target batch volume in liters (L)"},"boilTime":{"type":["number","null"],"description":"Boil time in minutes"},"efficiency":{"type":["number","null"],"description":"Efficiency percentage (0-100)"},"efficiencyType":{"type":["string","null"],"enum":["mash","brewhouse"],"description":"Efficiency type"},"fermentablesPercentMode":{"type":["boolean","null"],"description":"When true, fermentable amounts are calculated from percentages to hit targetOg"},"targetOg":{"type":["number","null"],"description":"Target OG in SG format (e.g., 1.050)"},"hopsScaleMode":{"type":["boolean","null"],"description":"When true, hop amounts are scaled to hit targetIBU"},"targetIBU":{"type":["number","null"],"description":"Target IBU value"},"fgOverride":{"type":["number","null"],"description":"Override calculated FG with this value (SG format, e.g., 1.012)"},"targetCo2Volumes":{"type":["number","null"],"description":"Target carbonation in volumes of CO2"},"mash":{"$ref":"#/components/schemas/MashProfile"},"fermentation":{"$ref":"#/components/schemas/FermentationProfile"}}},"equipment":{"allOf":[{"$ref":"#/components/schemas/Equipment"},{"type":"object"}]},"style":{"allOf":[{"$ref":"#/components/schemas/Style"},{"type":"object"}]},"water":{"allOf":[{"$ref":"#/components/schemas/Water"},{"type":"object"}]},"measuredValues":{"$ref":"#/components/schemas/WritableMeasuredValues"}}},"CreateBrewNote":{"type":"object","properties":{"type":{"type":"string","enum":["observation","issue","adjustment","note","reminder"],"default":"observation"},"content":{"type":"string","minLength":1,"maxLength":10000},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"]},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/WritableCustomFieldValue"},"description":"Values for active Brew Note-scoped Custom Fields"}},"required":["content"]},"UpdateBrewNote":{"type":"object","properties":{"type":{"type":"string","enum":["observation","issue","adjustment","note","reminder"]},"content":{"type":"string","minLength":1,"maxLength":10000},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"]},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/WritableCustomFieldValue"},"description":"Changed values for active Brew Note-scoped Custom Fields; omitted fields are preserved"}}},"BrewNoteListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BrewNote"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"FermentationReadingListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FermentationReading"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"InventoryFermentable":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"},"ingredientId":{"type":"string","description":"Package ingredient ID"},"name":{"type":"string","example":"Pale Malt 2-Row"},"supplier":{"type":["string","null"],"example":"Briess"},"quantity":{"type":"number","description":"Quantity in kg","example":25},"color":{"type":["number","null"],"description":"Color in SRM","example":2},"potential":{"type":["number","null"],"description":"Potential extract in PPG (points per pound per gallon)","example":37},"type":{"type":["string","null"],"example":"Grain"},"origin":{"type":["string","null"],"example":"US"},"colorOverride":{"type":["number","null"],"description":"Lot-specific color override (EBC)"},"potentialOverride":{"type":["number","null"],"description":"Lot-specific potential override in PPG"},"lotNumber":{"type":["string","null"],"description":"Lot number"},"expiryDate":{"type":["string","null"],"format":"date-time","description":"Expiry date"},"purchaseDate":{"type":["string","null"],"format":"date-time","description":"Purchase date"},"costPerKg":{"type":["number","null"],"description":"Cost per kg"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","ingredientId","name","supplier","quantity","color","potential","type","origin","colorOverride","potentialOverride","lotNumber","expiryDate","purchaseDate","costPerKg","notes","createdAt","updatedAt"]},"InventoryHop":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"},"ingredientId":{"type":"string","description":"Package ingredient ID"},"name":{"type":"string","example":"Cascade"},"supplier":{"type":["string","null"],"example":"YCH Hops"},"quantity":{"type":"number","description":"Quantity in grams","example":500},"alpha":{"type":["number","null"],"description":"Alpha acid %","example":5.5},"beta":{"type":["number","null"],"description":"Beta acid %"},"alphaAcidOverride":{"type":["number","null"],"description":"Lot-specific alpha acid override"},"form":{"type":["string","null"],"example":"Pellet"},"origin":{"type":["string","null"],"example":"US"},"year":{"type":["number","null"],"description":"Harvest year","example":2024},"lotNumber":{"type":["string","null"],"description":"Lot number"},"expiryDate":{"type":["string","null"],"format":"date-time","description":"Expiry date"},"purchaseDate":{"type":["string","null"],"format":"date-time","description":"Purchase date"},"costPerKg":{"type":["number","null"],"description":"Cost per kg"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","ingredientId","name","supplier","quantity","alpha","beta","alphaAcidOverride","form","origin","year","lotNumber","expiryDate","purchaseDate","costPerKg","notes","createdAt","updatedAt"]},"InventoryYeast":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"},"ingredientId":{"type":"string","description":"Package ingredient ID"},"name":{"type":"string","example":"Safale US-05"},"supplier":{"type":["string","null"],"example":"Fermentis"},"quantity":{"type":"number","description":"Number of packages","example":5},"quantityUnit":{"type":["string","null"],"description":"Quantity unit (pkg/ml/g/cells)","example":"pkg"},"type":{"type":["string","null"],"example":"Ale"},"form":{"type":["string","null"],"example":"Dry"},"attenuation":{"type":["number","null"],"description":"Attenuation %","example":75},"attenuationOverride":{"type":["number","null"],"description":"Lot-specific attenuation override"},"productId":{"type":["string","null"],"example":"US-05"},"lotNumber":{"type":["string","null"],"description":"Lot number"},"manufacturingDate":{"type":["string","null"],"format":"date-time","description":"Manufacturing date"},"expiryDate":{"type":["string","null"],"format":"date-time","description":"Expiry date"},"purchaseDate":{"type":["string","null"],"format":"date-time","description":"Purchase date"},"costPerUnit":{"type":["number","null"],"description":"Cost per unit"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","ingredientId","name","supplier","quantity","quantityUnit","type","form","attenuation","attenuationOverride","productId","lotNumber","manufacturingDate","expiryDate","purchaseDate","costPerUnit","notes","createdAt","updatedAt"]},"InventoryMisc":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"},"ingredientId":{"type":"string","description":"Package ingredient ID"},"name":{"type":"string","example":"Irish Moss"},"supplier":{"type":["string","null"]},"quantity":{"type":"number","description":"Quantity","example":100},"unit":{"type":["string","null"],"example":"g"},"type":{"type":["string","null"],"example":"Fining"},"use":{"type":["string","null"],"example":"Boil"},"lotNumber":{"type":["string","null"],"description":"Lot number"},"expiryDate":{"type":["string","null"],"format":"date-time","description":"Expiry date"},"purchaseDate":{"type":["string","null"],"format":"date-time","description":"Purchase date"},"costPerUnit":{"type":["number","null"],"description":"Cost per unit"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","ingredientId","name","supplier","quantity","unit","type","use","lotNumber","expiryDate","purchaseDate","costPerUnit","notes","createdAt","updatedAt"]},"Inventory":{"type":"object","properties":{"fermentables":{"type":"array","items":{"$ref":"#/components/schemas/InventoryFermentable"}},"hops":{"type":"array","items":{"$ref":"#/components/schemas/InventoryHop"}},"yeasts":{"type":"array","items":{"$ref":"#/components/schemas/InventoryYeast"}},"miscs":{"type":"array","items":{"$ref":"#/components/schemas/InventoryMisc"}}},"required":["fermentables","hops","yeasts","miscs"]},"InventoryFermentableListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryFermentable"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"InventoryHopListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryHop"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"InventoryYeastListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryYeast"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"InventoryMiscListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryMisc"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"CreateInventoryFermentable":{"type":"object","properties":{"ingredientId":{"type":"string","minLength":1,"description":"Package ingredient ID (required)"},"quantity":{"type":"number","minimum":0,"description":"Quantity in kg","example":25},"colorOverride":{"type":["number","null"],"minimum":0,"maximum":600},"potentialOverride":{"type":["number","null"],"minimum":0,"maximum":50},"lotNumber":{"type":["string","null"],"maxLength":100},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerKg":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}},"required":["ingredientId","quantity"]},"UpdateInventoryFermentable":{"type":"object","properties":{"quantity":{"type":"number","minimum":0,"description":"Quantity in kg","example":25},"colorOverride":{"type":["number","null"],"minimum":0,"maximum":600},"potentialOverride":{"type":["number","null"],"minimum":0,"maximum":50},"lotNumber":{"type":["string","null"],"maxLength":100},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerKg":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}}},"CreateInventoryHop":{"type":"object","properties":{"ingredientId":{"type":"string","minLength":1,"description":"Package ingredient ID (required)"},"quantity":{"type":"number","minimum":0,"description":"Quantity in grams","example":500},"alphaAcidOverride":{"type":["number","null"],"minimum":0,"maximum":30},"form":{"type":["string","null"],"enum":["pellet","whole","cryo","extract"]},"lotNumber":{"type":["string","null"],"maxLength":100},"harvestYear":{"type":["integer","null"],"minimum":1900,"maximum":2100},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerKg":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}},"required":["ingredientId","quantity"]},"UpdateInventoryHop":{"type":"object","properties":{"quantity":{"type":"number","minimum":0,"description":"Quantity in grams","example":500},"alphaAcidOverride":{"type":["number","null"],"minimum":0,"maximum":30},"form":{"type":["string","null"],"enum":["pellet","whole","cryo","extract"]},"lotNumber":{"type":["string","null"],"maxLength":100},"harvestYear":{"type":["integer","null"],"minimum":1900,"maximum":2100},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerKg":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}}},"CreateInventoryYeast":{"type":"object","properties":{"ingredientId":{"type":"string","minLength":1,"description":"Package ingredient ID (required)"},"quantity":{"type":"number","minimum":0,"description":"Number of packages","example":5},"quantityUnit":{"type":"string","enum":["pkg","ml","g","cells"],"default":"pkg"},"attenuationOverride":{"type":["number","null"],"minimum":0,"maximum":100},"lotNumber":{"type":["string","null"],"maxLength":100},"manufacturingDate":{"type":["string","null"],"format":"date-time"},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerUnit":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}},"required":["ingredientId","quantity"]},"UpdateInventoryYeast":{"type":"object","properties":{"quantity":{"type":"number","minimum":0,"description":"Number of packages","example":5},"quantityUnit":{"type":"string","enum":["pkg","ml","g","cells"],"default":"pkg"},"attenuationOverride":{"type":["number","null"],"minimum":0,"maximum":100},"lotNumber":{"type":["string","null"],"maxLength":100},"manufacturingDate":{"type":["string","null"],"format":"date-time"},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerUnit":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}}},"CreateInventoryMisc":{"type":"object","properties":{"ingredientId":{"type":"string","minLength":1,"description":"Package ingredient ID (required)"},"quantity":{"type":"number","minimum":0,"description":"Quantity","example":100},"quantityUnit":{"type":"string","enum":["g","ml","each","mg"],"default":"g"},"lotNumber":{"type":["string","null"],"maxLength":100},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerUnit":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}},"required":["ingredientId","quantity"]},"UpdateInventoryMisc":{"type":"object","properties":{"quantity":{"type":"number","minimum":0,"description":"Quantity","example":100},"quantityUnit":{"type":"string","enum":["g","ml","each","mg"],"default":"g"},"lotNumber":{"type":["string","null"],"maxLength":100},"expiryDate":{"type":["string","null"],"format":"date-time"},"purchaseDate":{"type":["string","null"],"format":"date-time"},"costPerUnit":{"type":["number","null"],"minimum":0},"supplier":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":500}}},"EquipmentProfile":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"},"name":{"type":"string","example":"My Brew Kettle"},"description":{"type":["string","null"]},"isDefault":{"type":"boolean","description":"Whether this is the default profile"},"batchVolume":{"type":"number","description":"Target batch volume in liters (L)","example":20},"batchVolumeReference":{"type":["string","null"],"enum":["fermenter","kettle"],"description":"Where batch volume is measured: fermenter (into fermenter) or kettle (post-boil)"},"boilTime":{"type":"number","description":"Boil time in minutes","example":60},"preBoilVolume":{"type":["number","null"],"description":"Pre-boil volume in liters (L)"},"boilOffRate":{"type":"number","description":"Boil-off rate value; its unit is selected by boilOffRateMode","example":4},"boilOffRateMode":{"type":"string","enum":["volume","percentage"],"description":"Whether boilOffRate is liters per hour or percent of starting pre-boil volume per hour","example":"volume"},"trubChillerLoss":{"type":["number","null"],"description":"Trub and chiller loss in liters (L)"},"mashTunDeadSpace":{"type":["number","null"],"description":"Mash tun dead space in liters (L)"},"mashTunLoss":{"type":["number","null"],"description":"Mash tun loss in liters (L)"},"fermenterLoss":{"type":["number","null"],"description":"Fermenter loss in liters (L)"},"hltDeadSpace":{"type":["number","null"],"description":"HLT dead space in liters (L)"},"fermenterTopUp":{"type":["number","null"],"description":"Fermenter top-up water in liters (L)"},"brewHouseEfficiency":{"type":"number","description":"Brewhouse efficiency percentage (%)","example":72},"mashEfficiency":{"type":["number","null"],"description":"Mash efficiency percentage (%)"},"efficiencyDisplay":{"type":["string","null"],"enum":["brewhouse","mash"],"description":"Display preference for efficiency"},"hopUtilization":{"type":["number","null"],"description":"Hop utilization multiplier (1.0 = 100%)"},"mashTunMaxVolume":{"type":["number","null"],"description":"Usable total mash tun capacity in liters (strike water plus grain displacement)"},"kettleMaxVolume":{"type":["number","null"],"description":"Maximum pre-boil kettle capacity in liters (L)"},"mashTunMinVolume":{"type":["number","null"],"description":"Minimum mash tun fill in liters (strike water plus grain displacement)"},"hltMaxVolume":{"type":["number","null"],"description":"Most water the hot water tank heats per fill (strike or sparge), in liters (L)"},"hltMinVolume":{"type":["number","null"],"description":"Least water the hot water tank needs per fill (strike or sparge), in liters (L)"},"grainAbsorptionRate":{"type":["number","null"],"description":"Grain absorption rate in liters per kg (L/kg)"},"waterToGrainRatio":{"type":["number","null"],"description":"Water to grain ratio in liters per kg (L/kg)"},"calculationMethod":{"type":["string","null"],"enum":["default","batch_sparge","no_sparge","custom"],"description":"Water calculation method"},"mashWaterMin":{"type":["number","null"],"description":"Legacy: optional minimum strike water process bound in liters (L). Prefer mashTunMinVolume / hltMinVolume."},"mashWaterMax":{"type":["number","null"],"description":"Legacy: optional maximum strike water process limit in liters (L). Prefer mashTunMaxVolume / hltMaxVolume."},"spargeWaterMin":{"type":["number","null"],"description":"Legacy: minimum sparge water volume in liters (L). Prefer hltMinVolume."},"spargeWaterMax":{"type":["number","null"],"description":"Legacy: maximum sparge water volume in liters (L). Prefer hltMaxVolume."},"includeGrainVolume":{"type":["boolean","null"],"description":"Legacy: whether mashWaterMin and mashWaterMax include grain displacement"},"overflowTarget":{"type":["string","null"],"enum":["top_up","mash"],"description":"Where excess water goes"},"altitude":{"type":["number","null"],"description":"Altitude in meters (affects boil temp)"},"boilTemperature":{"type":["number","null"],"description":"Boil temperature in °C"},"hopstandTemperature":{"type":["number","null"],"description":"Hopstand/whirlpool temperature in °C"},"hopstandDuration":{"type":["number","null"],"description":"Hopstand duration in minutes"},"grainTemperature":{"type":["number","null"],"description":"Grain temperature in °C (for strike temp calc)"},"mashTunHeatCapacity":{"type":["number","null"],"description":"Mash tun heat capacity in Cal/°C (0 = ignore)"},"coolingShrinkage":{"type":["number","null"],"description":"Cooling shrinkage percentage (%)"},"calculateStrikeTemp":{"type":["boolean","null"],"description":"Auto-calculate strike temperature"},"spargeTemperature":{"type":["number","null"],"description":"Sparge water temperature in °C"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","isDefault","batchVolume","batchVolumeReference","boilTime","preBoilVolume","boilOffRate","boilOffRateMode","trubChillerLoss","mashTunDeadSpace","mashTunLoss","fermenterLoss","hltDeadSpace","fermenterTopUp","brewHouseEfficiency","mashEfficiency","efficiencyDisplay","hopUtilization","mashTunMaxVolume","kettleMaxVolume","mashTunMinVolume","hltMaxVolume","hltMinVolume","grainAbsorptionRate","waterToGrainRatio","calculationMethod","mashWaterMin","mashWaterMax","spargeWaterMin","spargeWaterMax","includeGrainVolume","overflowTarget","altitude","boilTemperature","hopstandTemperature","hopstandDuration","grainTemperature","mashTunHeatCapacity","coolingShrinkage","calculateStrikeTemp","spargeTemperature","createdAt","updatedAt"]},"EquipmentListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EquipmentProfile"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"CreateEquipmentProfile":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Profile name","example":"My BIAB Setup"},"description":{"type":["string","null"],"maxLength":2000},"isDefault":{"type":"boolean"},"batchVolume":{"type":"number","exclusiveMinimum":0,"description":"Target batch volume in liters (L)","example":20},"batchVolumeReference":{"type":"string","enum":["fermenter","kettle"]},"boilTime":{"type":"integer","minimum":0},"preBoilVolume":{"type":["number","null"]},"boilOffRate":{"type":"number","minimum":0},"boilOffRateMode":{"type":"string","enum":["volume","percentage"]},"trubChillerLoss":{"type":["number","null"],"minimum":0},"mashTunDeadSpace":{"type":["number","null"],"minimum":0},"mashTunLoss":{"type":["number","null"],"minimum":0},"fermenterLoss":{"type":["number","null"],"minimum":0},"hltDeadSpace":{"type":["number","null"],"minimum":0},"fermenterTopUp":{"type":["number","null"],"minimum":0},"brewHouseEfficiency":{"type":"number","minimum":0,"maximum":100},"mashEfficiency":{"type":["number","null"],"minimum":0,"maximum":100},"efficiencyDisplay":{"type":"string","enum":["brewhouse","mash"]},"hopUtilization":{"type":["number","null"],"minimum":0},"mashTunMaxVolume":{"type":["number","null"]},"mashTunMinVolume":{"type":["number","null"],"minimum":0},"kettleMaxVolume":{"type":["number","null"]},"hltMaxVolume":{"type":["number","null"],"minimum":0},"hltMinVolume":{"type":["number","null"],"minimum":0},"grainAbsorptionRate":{"type":["number","null"]},"waterToGrainRatio":{"type":["number","null"]},"calculationMethod":{"type":"string","enum":["default","batch_sparge","no_sparge","custom"]},"mashWaterMin":{"type":["number","null"]},"mashWaterMax":{"type":["number","null"]},"spargeWaterMin":{"type":["number","null"]},"spargeWaterMax":{"type":["number","null"]},"includeGrainVolume":{"type":"boolean"},"overflowTarget":{"type":"string","enum":["top_up","mash"]},"altitude":{"type":["number","null"]},"boilTemperature":{"type":["number","null"]},"hopstandTemperature":{"type":["number","null"]},"hopstandDuration":{"type":["integer","null"],"minimum":0},"grainTemperature":{"type":["number","null"]},"mashTunHeatCapacity":{"type":["number","null"],"minimum":0},"coolingShrinkage":{"type":["number","null"],"minimum":0},"calculateStrikeTemp":{"type":"boolean"},"spargeTemperature":{"type":["number","null"]}},"required":["name","batchVolume"]},"UpdateEquipmentProfile":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":["string","null"],"maxLength":2000},"isDefault":{"type":"boolean"},"batchVolume":{"type":"number","exclusiveMinimum":0},"batchVolumeReference":{"type":"string","enum":["fermenter","kettle"]},"boilTime":{"type":"integer","minimum":0},"preBoilVolume":{"type":["number","null"]},"boilOffRate":{"type":"number","minimum":0},"boilOffRateMode":{"type":"string","enum":["volume","percentage"]},"trubChillerLoss":{"type":["number","null"],"minimum":0},"mashTunDeadSpace":{"type":["number","null"],"minimum":0},"mashTunLoss":{"type":["number","null"],"minimum":0},"fermenterLoss":{"type":["number","null"],"minimum":0},"hltDeadSpace":{"type":["number","null"],"minimum":0},"fermenterTopUp":{"type":["number","null"],"minimum":0},"brewHouseEfficiency":{"type":"number","minimum":0,"maximum":100},"mashEfficiency":{"type":["number","null"],"minimum":0,"maximum":100},"efficiencyDisplay":{"type":"string","enum":["brewhouse","mash"]},"hopUtilization":{"type":["number","null"],"minimum":0},"mashTunMaxVolume":{"type":["number","null"]},"mashTunMinVolume":{"type":["number","null"],"minimum":0},"kettleMaxVolume":{"type":["number","null"]},"hltMaxVolume":{"type":["number","null"],"minimum":0},"hltMinVolume":{"type":["number","null"],"minimum":0},"grainAbsorptionRate":{"type":["number","null"]},"waterToGrainRatio":{"type":["number","null"]},"calculationMethod":{"type":"string","enum":["default","batch_sparge","no_sparge","custom"]},"mashWaterMin":{"type":["number","null"]},"mashWaterMax":{"type":["number","null"]},"spargeWaterMin":{"type":["number","null"]},"spargeWaterMax":{"type":["number","null"]},"includeGrainVolume":{"type":"boolean"},"overflowTarget":{"type":"string","enum":["top_up","mash"]},"altitude":{"type":["number","null"]},"boilTemperature":{"type":["number","null"]},"hopstandTemperature":{"type":["number","null"]},"hopstandDuration":{"type":["integer","null"],"minimum":0},"grainTemperature":{"type":["number","null"]},"mashTunHeatCapacity":{"type":["number","null"],"minimum":0},"coolingShrinkage":{"type":["number","null"],"minimum":0},"calculateStrikeTemp":{"type":"boolean"},"spargeTemperature":{"type":["number","null"]}}},"StyleProfile":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"},"name":{"type":"string","example":"American IPA"},"category":{"type":["string","null"],"example":"IPA"},"categoryNumber":{"type":["string","null"],"example":"21A"},"guidelines":{"type":["string","null"],"example":"BJCP 2021"},"description":{"type":["string","null"]},"ogMin":{"type":["number","null"],"example":1.056},"ogMax":{"type":["number","null"],"example":1.07},"fgMin":{"type":["number","null"],"example":1.008},"fgMax":{"type":["number","null"],"example":1.014},"ibuMin":{"type":["number","null"],"example":40},"ibuMax":{"type":["number","null"],"example":70},"srmMin":{"type":["number","null"],"example":6},"srmMax":{"type":["number","null"],"example":14},"abvMin":{"type":["number","null"],"example":5.5},"abvMax":{"type":["number","null"],"example":7.5},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","category","categoryNumber","guidelines","description","ogMin","ogMax","fgMin","fgMax","ibuMin","ibuMax","srmMin","srmMax","abvMin","abvMax","createdAt","updatedAt"]},"StyleListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StyleProfile"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"CreateStyleProfile":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Style name","example":"American IPA"},"category":{"type":["string","null"],"maxLength":100},"categoryNumber":{"type":["string","null"],"maxLength":10},"guidelines":{"type":["string","null"],"maxLength":100},"description":{"type":["string","null"],"maxLength":5000},"ogMin":{"type":["number","null"]},"ogMax":{"type":["number","null"]},"fgMin":{"type":["number","null"]},"fgMax":{"type":["number","null"]},"ibuMin":{"type":["number","null"]},"ibuMax":{"type":["number","null"]},"srmMin":{"type":["number","null"]},"srmMax":{"type":["number","null"]},"abvMin":{"type":["number","null"]},"abvMax":{"type":["number","null"]}},"required":["name"]},"UpdateStyleProfile":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"category":{"type":["string","null"],"maxLength":100},"categoryNumber":{"type":["string","null"],"maxLength":10},"guidelines":{"type":["string","null"],"maxLength":100},"description":{"type":["string","null"],"maxLength":5000},"ogMin":{"type":["number","null"]},"ogMax":{"type":["number","null"]},"fgMin":{"type":["number","null"]},"fgMax":{"type":["number","null"]},"ibuMin":{"type":["number","null"]},"ibuMax":{"type":["number","null"]},"srmMin":{"type":["number","null"]},"srmMax":{"type":["number","null"]},"abvMin":{"type":["number","null"]},"abvMax":{"type":["number","null"]}}},"ApiMashStep":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["infusion","temperature","decoction"]},"targetTemp":{"type":"number","description":"Target temperature in °C"},"duration":{"type":"number","description":"Duration in minutes"},"rampTime":{"type":["number","null"],"description":"Ramp time in minutes"},"waterAmount":{"type":["number","null"],"description":"Water amount in liters (infusion steps)"},"infusionWaterTemp":{"type":["number","null"],"description":"Infusion water temperature in °C"},"decoctionVolume":{"type":["number","null"]},"decoctionReturnTemp":{"type":["number","null"]},"decoctionBoilDuration":{"type":["number","null"]},"decoctionVolumeLoss":{"type":["number","null"]},"tempLossRate":{"type":["number","null"],"description":"Temperature loss rate in °C/hour"}},"required":["name","type","targetTemp","duration"]},"MashProfileResponse":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"},"name":{"type":"string","example":"Single Infusion, Medium Body"},"description":{"type":["string","null"]},"grainTemp":{"type":["number","null"],"description":"Default grain temperature in °C"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ApiMashStep"}},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","grainTemp","steps","isDefault","createdAt","updatedAt"]},"MashProfileListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MashProfileResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"ApiFermentationStage":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["primary","secondary","tertiary","cold_crash","conditioning","carbonation"]},"targetTemp":{"type":"number","description":"Target temperature in °C"},"duration":{"type":"number","description":"Duration in days"},"rampTime":{"type":["number","null"],"description":"Ramp time in hours"},"pressure":{"type":["number","null"],"description":"Pressure in PSI (pressurized fermentation)"},"spundingEnabled":{"type":"boolean","description":"Whether this is the profile's single Spunding Stage"},"spundingSafetyMarginPoints":{"type":"number","minimum":0,"description":"Explicit spunding safety margin in SG gravity points (defaults to 4)","example":4}},"required":["name","type","targetTemp","duration"]},"FermentationProfileResponse":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"},"name":{"type":"string","example":"Ale, Two Stage"},"description":{"type":["string","null"]},"stages":{"type":"array","items":{"$ref":"#/components/schemas/ApiFermentationStage"}},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","stages","isDefault","createdAt","updatedAt"]},"FermentationProfileListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FermentationProfileResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"WaterProfileResponse":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"},"name":{"type":"string","example":"London"},"description":{"type":["string","null"]},"calcium":{"type":"number","description":"Calcium in ppm"},"magnesium":{"type":"number","description":"Magnesium in ppm"},"sodium":{"type":"number","description":"Sodium in ppm"},"chloride":{"type":"number","description":"Chloride in ppm"},"sulfate":{"type":"number","description":"Sulfate in ppm"},"bicarbonate":{"type":"number","description":"Bicarbonate in ppm"},"ph":{"type":["number","null"],"description":"Source water pH"},"conductivity":{"type":["number","null"],"description":"Conductivity in µS/cm"},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","calcium","magnesium","sodium","chloride","sulfate","bicarbonate","ph","conductivity","isDefault","createdAt","updatedAt"]},"WaterProfileListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WaterProfileResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string","description":"Field definition ID"},"key":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$","description":"Immutable brewer-unique lowercase kebab-case integration key","example":"lab-report-url"},"name":{"type":"string","example":"Brew Day pH"},"description":{"type":["string","null"]},"fieldType":{"type":"string","enum":["text","number","integer","date","time","datetime","boolean","select","url"],"description":"Data type of the field"},"scope":{"type":"string","enum":["brew","brew_note"],"description":"Whether values belong to the Brew or independently to Brew Notes"},"placement":{"type":["string","null"],"enum":["brew_details","brew_day","fermentation","packaging","tasting"],"description":"Brew interface location; null for Brew Note-scoped fields"},"stage":{"type":"string","enum":["brew_details","brew_day","fermentation","post_fermentation","packaging","tasting","brew_notes"],"description":"Deprecated compatibility alias for placement, or brew_notes for Brew Note fields","deprecated":true},"options":{"type":["object","null"],"properties":{"choices":{"type":"array","items":{"type":"string"}}},"required":["choices"],"description":"Options for select fields"},"unit":{"type":["string","null"],"description":"Unit label (e.g. pH, °C, g/L)","example":"pH"},"placeholder":{"type":["string","null"]},"defaultValue":{"type":["string","null"],"description":"Default value (stored as string)"},"isRequired":{"type":"boolean"},"displayOrder":{"type":"integer"},"archivedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","key","name","description","fieldType","scope","placement","stage","options","unit","placeholder","defaultValue","isRequired","displayOrder","archivedAt","createdAt","updatedAt"]},"CustomFieldDefinitionListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldDefinition"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"CustomFieldEffectiveValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]},"CustomFieldValuesByKey":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CustomFieldEffectiveValue"}},"CustomFieldLookupNote":{"type":"object","properties":{"id":{"type":"string","description":"Note ID"},"type":{"type":"string","enum":["observation","issue","adjustment","note","reminder"],"description":"Note type/category"},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"],"description":"Brewing phase when note was added"},"timestamp":{"type":"string","format":"date-time","description":"When the note was created"},"content":{"type":"string","description":"Note content"},"values":{"$ref":"#/components/schemas/CustomFieldValuesByKey"}},"required":["id","type","timestamp","content","values"]},"CustomFieldLookupResponse":{"type":"object","properties":{"values":{"$ref":"#/components/schemas/CustomFieldValuesByKey"},"notes":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldLookupNote"}},"unknownKeys":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$","description":"Immutable brewer-unique lowercase kebab-case integration key","example":"lab-report-url"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["values","notes","unknownKeys","pagination"]},"TicketAttachment":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"}},"required":["url","filename","contentType","size"]},"Ticket":{"type":"object","properties":{"id":{"type":"string","description":"Ticket ID"},"shortId":{"type":["integer","null"],"description":"Short numeric ticket ID (e.g. 42)"},"type":{"type":"string","enum":["bug_report"],"description":"Ticket type (always bug_report; feature requests are feedback threads)","example":"bug_report"},"task":{"type":"string","description":"What the user is trying to do"},"details":{"type":["string","null"],"description":"Additional details"},"severity":{"type":["string","null"],"enum":["minor","medium","blocking"],"description":"Severity"},"pageUrl":{"type":"string","description":"Page URL where feedback was submitted"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Context captured with the report (brew ID, tab, browser, ...)"},"attachments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TicketAttachment"},"description":"Bug report screenshot attachments"},"status":{"type":"string","enum":["new","acked","in_progress","waiting_customer","resolved","wontfix","reopened","added_to_external"],"description":"Current ticket status","example":"new"},"adminNotes":{"type":["string","null"],"description":"Internal admin notes"},"milestoneId":{"type":["string","null"],"description":"Linked milestone ID"},"milestoneName":{"type":["string","null"],"description":"Linked milestone name"},"resolvedAt":{"type":["string","null"],"format":"date-time","description":"When the ticket was resolved"},"statusUpdatedAt":{"type":["string","null"],"format":"date-time","description":"When the status was last changed"},"lastActivityAt":{"type":["string","null"],"format":"date-time","description":"Last activity timestamp"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"userId":{"type":"string","description":"Submitting user ID"},"userName":{"type":["string","null"],"description":"Submitting user display name"},"userEmail":{"type":["string","null"],"description":"Submitting user email"}},"required":["id","shortId","type","task","details","severity","pageUrl","metadata","attachments","status","adminNotes","milestoneId","milestoneName","resolvedAt","statusUpdatedAt","lastActivityAt","createdAt","userId","userName","userEmail"]},"TicketListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ticket"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"TicketMessage":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"subject":{"type":"string","description":"Message subject"},"body":{"type":"string","description":"Message body"},"isUserReply":{"type":"boolean","description":"Whether this is a user reply"},"attachments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TicketAttachment"},"description":"Screenshots the customer attached to this reply"},"senderName":{"type":["string","null"],"description":"Sender display name"},"createdAt":{"type":"string","format":"date-time","description":"When the message was sent"}},"required":["id","subject","body","isUserReply","attachments","senderName","createdAt"]},"TicketAgentRun":{"type":"object","properties":{"id":{"type":"string","description":"Agent run ID (the `run:` line of the dispatch payload)"},"reason":{"type":"string","enum":["new_bug","customer_reply"],"description":"Why the run was started"},"status":{"type":"string","enum":["dispatching","running","completed","failed","expired"],"description":"dispatching/running are in flight; expired = never reported back within 3 hours"},"sessionId":{"type":["string","null"],"description":"Claude Code session ID"},"sessionUrl":{"type":["string","null"],"description":"Claude Code session URL"},"error":{"type":["string","null"],"description":"Dispatch error or the agent's failure reason"},"summary":{"type":["string","null"],"description":"Outcome the agent reported when it finished"},"createdAt":{"type":"string","format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","reason","status","sessionId","sessionUrl","error","summary","createdAt","finishedAt"]},"TicketNote":{"type":"object","properties":{"id":{"type":"string"},"actor":{"type":"string","enum":["team","agent"],"description":"`team` (Bernd) or `agent` (bug agent)"},"agentRunId":{"type":["string","null"],"description":"Agent run the note belongs to"},"body":{"type":"string","description":"Internal note (Markdown), never shown to the customer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","actor","agentRunId","body","createdAt"]},"TicketDetailResponse":{"type":"object","properties":{"ticket":{"$ref":"#/components/schemas/Ticket"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/TicketMessage"}},"bountyAwarded":{"type":"integer","description":"Total bounty points awarded"},"userLocale":{"type":"string","enum":["en","de"],"description":"The customer's UI language; reply in it"},"agentRuns":{"type":"array","items":{"$ref":"#/components/schemas/TicketAgentRun"},"description":"Bug agent runs, newest first"},"notes":{"type":"array","items":{"$ref":"#/components/schemas/TicketNote"},"description":"Internal notes, oldest first"}},"required":["ticket","messages","bountyAwarded","userLocale","agentRuns","notes"]},"CreateTicket":{"type":"object","properties":{"type":{"type":"string","enum":["bug_report"],"default":"bug_report","description":"Ticket type (only bug_report)","example":"bug_report"},"task":{"type":"string","minLength":1,"description":"What the user is trying to do"},"details":{"type":"string","description":"Additional details"},"severity":{"type":"string","enum":["minor","medium","blocking"],"description":"Severity (defaults to medium)"},"adminNotes":{"type":"string","description":"Internal admin notes"},"status":{"type":"string","enum":["new","acked","in_progress","waiting_customer","resolved","wontfix","reopened","added_to_external"],"default":"new","description":"Initial status","example":"new"},"userId":{"type":"string","description":"Assign to user ID (omit for first admin)"}},"required":["task"]},"UpdateTicket":{"type":"object","properties":{"status":{"type":"string","enum":["new","acked","in_progress","waiting_customer","resolved","wontfix","reopened","added_to_external"],"description":"New status"},"severity":{"type":"string","enum":["minor","medium","blocking"],"description":"Severity"},"adminNotes":{"type":"string","description":"Internal admin notes"},"milestoneId":{"type":["string","null"],"description":"Milestone ID (null to unset)"}}},"TicketMessageListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TicketMessage"}}},"required":["data"]},"ReplyToTicket":{"type":"object","properties":{"subject":{"type":"string","minLength":1,"description":"Reply subject"},"body":{"type":"string","minLength":1,"description":"Reply body"},"updateStatus":{"type":"string","enum":["new","acked","in_progress","waiting_customer","resolved","wontfix","reopened","added_to_external"],"description":"Optionally update ticket status"},"confirmSend":{"type":"boolean","enum":[true],"description":"Must be true to confirm sending"},"actor":{"type":"string","enum":["team","agent"],"default":"team","description":"`agent`: sent without an admin sender and signed \"BrewForge assistant (automated)\" in the customer's language"}},"required":["subject","body","confirmSend"]},"TicketReplyResponse":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"subject":{"type":"string","description":"Reply subject"},"body":{"type":"string","description":"Reply body"},"createdAt":{"type":"string","format":"date-time","description":"Reply timestamp"}},"required":["id","subject","body","createdAt"]},"TicketStats":{"type":"object","properties":{"total":{"type":"integer","description":"Total tickets"},"new":{"type":"integer","description":"New tickets"},"acked":{"type":"integer","description":"Acknowledged tickets"},"inProgress":{"type":"integer","description":"In progress tickets"},"waitingCustomer":{"type":"integer","description":"Awaiting customer response"},"reopened":{"type":"integer","description":"Reopened tickets"},"resolved":{"type":"integer","description":"Resolved tickets"},"wontfix":{"type":"integer","description":"Won't fix tickets"},"blocking":{"type":"integer","description":"Blocking severity count"},"blockingOpen":{"type":"integer","description":"Open blocking tickets"}},"required":["total","new","acked","inProgress","waitingCustomer","reopened","resolved","wontfix","blocking","blockingOpen"]},"BrewListQuery":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Items per page"},"status":{"$ref":"#/components/schemas/BrewStatus"}},"required":["page","limit"]},"BrewIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"BrewUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"BrewDeleteIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"BrewCustomFieldsIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"BrewCustomFieldsLookupQuery":{"type":"object","properties":{"page":{"type":["integer","null"],"minimum":1,"description":"Page number (1-indexed)","example":1},"limit":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Items per page (max 100)","example":20},"keys":{"type":"string","minLength":1,"description":"Comma-separated Custom Field keys (maximum 100 unique keys)","example":"lab-report-url,fermenter-number"}},"required":["keys"]},"BrewNotesListIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"BrewNoteIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"BrewNoteSingleIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"},"noteId":{"type":"string","description":"Note ID"}},"required":["id","noteId"]},"BrewNoteUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"},"noteId":{"type":"string","description":"Note ID"}},"required":["id","noteId"]},"BrewNoteDeleteIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"},"noteId":{"type":"string","description":"Note ID"}},"required":["id","noteId"]},"BrewReadingsIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"BrewReadingsPostIdParam":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Brew ID"}},"required":["id"]},"InventoryFermentableIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryFermentableUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryFermentableDeleteIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryHopIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryHopUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryHopDeleteIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryYeastIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryYeastUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryYeastDeleteIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryMiscIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryMiscUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"InventoryMiscDeleteIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Inventory item ID"}},"required":["id"]},"EquipmentIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"}},"required":["id"]},"StyleIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"}},"required":["id"]},"MashProfileIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"}},"required":["id"]},"FermentationProfileIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"}},"required":["id"]},"WaterProfileIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Profile ID"}},"required":["id"]},"CustomFieldIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Field definition ID"}},"required":["id"]},"AdminTicketIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"}},"required":["id"]},"AdminTicketUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"}},"required":["id"]},"AdminTicketMessagesIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"}},"required":["id"]},"AdminTicketReplyIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"}},"required":["id"]},"AdminTicketNoteIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"}},"required":["id"]},"AdminTicketAgentRunParams":{"type":"object","properties":{"id":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"},"runId":{"type":"string","description":"Agent run ID (the `run:` line of the dispatch payload)"}},"required":["id","runId"]},"AdminFeedbackThreadIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackThreadUpdateIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackPostThreadIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackParticipantsThreadIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackAnswerThreadIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackMergeThreadIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackUnmergeThreadIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackLinkThreadIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackLinkParams":{"type":"object","properties":{"id":{"type":"string","description":"Thread number or id","example":"118"},"linkId":{"type":"string","description":"Link id"}},"required":["id","linkId"]},"AdminFeedbackModerationPostIdParam":{"type":"object","properties":{"postId":{"type":"string","description":"Post id"}},"required":["postId"]},"AdminFeedbackImplementationContextIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackQuestionnairesIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackCreateQuestionnaireIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"}},"required":["id"]},"AdminFeedbackQuestionnaireIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Questionnaire id"}},"required":["id"]},"AdminFeedbackOpenQuestionnaireIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Questionnaire id"}},"required":["id"]},"AdminFeedbackCloseQuestionnaireIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Questionnaire id"}},"required":["id"]},"AdminFeedbackQuestionnaireResultsIdParam":{"type":"object","properties":{"id":{"type":"string","description":"Questionnaire id"}},"required":["id"]},"AdminFeedbackQuestionnaireResponseParams":{"type":"object","properties":{"id":{"type":"string","description":"Questionnaire id"},"responseId":{"type":"string","description":"Response id"}},"required":["id","responseId"]},"PublicCalculatorAttribution":{"type":"object","properties":{"message":{"type":"string"},"source":{"type":"string"},"url":{"type":"string","format":"uri"},"about":{"type":"string"}},"required":["message","source","url","about"],"description":"Included in every response. Please credit BrewForge (https://brewforge.sh) when you use a result."},"PublicCalculatorResponse":{"type":"object","properties":{"calculator":{"type":"string","description":"Calculator name (URL segment)"},"title":{"type":"string"},"formula":{"type":"string","description":"Short name of the formula or model used"},"inputs":{"type":"object","additionalProperties":{},"description":"Normalized inputs with defaults filled in; numbers carry their unit as { value, unit }"},"units":{"type":"object","additionalProperties":{"type":"string"},"description":"Units used per unit kind (temperature, volume, gravity, …)"},"results":{"type":"object","additionalProperties":{},"description":"Results; numbers carry their unit as { value, unit }"},"notes":{"type":"array","items":{"type":"string"},"description":"Assumptions and warnings about the result"},"links":{"type":"object","properties":{"calculator":{"type":"string","format":"uri","description":"The calculator page with the same math"},"docs":{"type":"string","format":"uri"}},"required":["docs"]},"attribution":{"$ref":"#/components/schemas/PublicCalculatorAttribution"}},"required":["calculator","title","formula","inputs","units","results","links","attribution"],"description":"Calculator result"},"PublicCalculatorError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"invalid_parameters, or a calculator-specific code such as fgNotBelowOg"},"message":{"type":"string","description":"What is wrong, naming the parameter"},"issues":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string"},"message":{"type":"string"}},"required":["param","message"]}}},"required":["code","message"]},"usage":{"type":"object","properties":{"endpoint":{"type":"string"},"summary":{"type":"string"},"parameters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"}},"required":["name","required","description"]}},"example":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"}},"required":["endpoint","summary","parameters","example","docs"],"description":"The expected parameters and a working example URL"},"attribution":{"$ref":"#/components/schemas/PublicCalculatorAttribution"}},"required":["error","attribution"]},"CampaignDraw":{"type":"object","properties":{"id":{"type":"string"},"prize":{"type":"string","enum":["free_pro","trmnl"]},"kind":{"type":"string","enum":["initial","redraw"]},"eligibleCount":{"type":"integer"},"eligibleHash":{"type":"string","description":"SHA-256 (hex) over the sorted eligible user ids, one per line"},"seed":{"type":"string","description":"Random 256-bit seed (hex); winners = pickWinners(sorted ids, seed, winnersRequested)"},"winnersRequested":{"type":"integer"},"winnerUserIds":{"type":"array","items":{"type":"string"}},"replacesPrizeId":{"type":["string","null"]},"drawnBy":{"type":"string"},"note":{"type":["string","null"]},"drawnAt":{"type":"string","format":"date-time"},"verified":{"type":"boolean","description":"Recomputing from seed + eligible list gives the stored hash and winners"}},"required":["id","prize","kind","eligibleCount","eligibleHash","seed","winnersRequested","winnerUserIds","replacesPrizeId","drawnBy","note","drawnAt","verified"]},"CampaignPrize":{"type":"object","properties":{"id":{"type":"string"},"prize":{"type":"string","enum":["free_pro","trmnl"]},"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["won","revoked"]},"drawId":{"type":"string"},"awardedAt":{"type":"string","format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"revokeReason":{"type":["string","null"]},"proStatus":{"type":["string","null"],"enum":["trialing","active"],"description":"The winner's Pro subscription now: trialing (extend the trial by a year in Polar), active (already paying), null (redeems 100% off at checkout)"}},"required":["id","prize","userId","name","email","status","drawId","awardedAt","revokedAt","revokeReason","proStatus"]},"CampaignOverview":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"freeProEntryEndsAt":{"type":"string","format":"date-time"},"discountEndsAt":{"type":"string","format":"date-time"},"discountPercent":{"type":"integer"},"trmnlDrawOpensAt":{"type":"string","format":"date-time"},"trmnlCountries":{"type":"array","items":{"type":"string"}}},"required":["id","name","startsAt","freeProEntryEndsAt","discountEndsAt","discountPercent","trmnlDrawOpensAt","trmnlCountries"]},"phase":{"type":"string","enum":["upcoming","open","ended"]},"participants":{"type":"integer"},"freeProEntries":{"type":"integer","description":"Participants who joined inside the free-Pro window"},"freePro":{"type":"object","properties":{"canDraw":{"type":"boolean","description":"The entry window has closed (free Pro) or the draw has opened (TRMNL OG)"},"drawn":{"type":"boolean","description":"The one initial draw already ran"},"winnersPerDraw":{"type":"integer"},"eligibility":{"type":["object","null"],"properties":{"prize":{"type":"string","enum":["free_pro","trmnl"]},"eligible":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"detail":{"type":["string","null"],"description":"Free Pro: joinedAt (ISO). TRMNL OG: billing country (ISO alpha-2)."}},"required":["userId","name","email","detail"]}},"excluded":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"detail":{"type":["string","null"],"description":"Free Pro: joinedAt (ISO). TRMNL OG: billing country (ISO alpha-2)."},"reason":{"type":"string","enum":["pro_at_join","no_billing_country","other_country","lookup_failed"]}},"required":["userId","name","email","detail","reason"]}}},"required":["prize","eligible","excluded"],"description":"Null when skipped (includeTrmnl=false) or when the lookup failed (see error)"},"error":{"type":["string","null"]}},"required":["canDraw","drawn","winnersPerDraw","eligibility","error"]},"trmnl":{"type":"object","properties":{"canDraw":{"type":"boolean","description":"The entry window has closed (free Pro) or the draw has opened (TRMNL OG)"},"drawn":{"type":"boolean","description":"The one initial draw already ran"},"winnersPerDraw":{"type":"integer"},"eligibility":{"type":["object","null"],"properties":{"prize":{"type":"string","enum":["free_pro","trmnl"]},"eligible":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"detail":{"type":["string","null"],"description":"Free Pro: joinedAt (ISO). TRMNL OG: billing country (ISO alpha-2)."}},"required":["userId","name","email","detail"]}},"excluded":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"detail":{"type":["string","null"],"description":"Free Pro: joinedAt (ISO). TRMNL OG: billing country (ISO alpha-2)."},"reason":{"type":"string","enum":["pro_at_join","no_billing_country","other_country","lookup_failed"]}},"required":["userId","name","email","detail","reason"]}}},"required":["prize","eligible","excluded"],"description":"Null when skipped (includeTrmnl=false) or when the lookup failed (see error)"},"error":{"type":["string","null"]}},"required":["canDraw","drawn","winnersPerDraw","eligibility","error"]},"draws":{"type":"array","items":{"$ref":"#/components/schemas/CampaignDraw"}},"prizes":{"type":"array","items":{"$ref":"#/components/schemas/CampaignPrize"}}},"required":["campaign","phase","participants","freeProEntries","freePro","trmnl","draws","prizes"]},"CampaignDrawResult":{"type":"object","properties":{"draw":{"type":"object","properties":{"id":{"type":"string"},"prize":{"type":"string","enum":["free_pro","trmnl"]},"kind":{"type":"string","enum":["initial","redraw"]},"eligibleCount":{"type":"integer"},"eligibleHash":{"type":"string","description":"SHA-256 (hex) over the sorted eligible user ids, one per line"},"seed":{"type":"string","description":"Random 256-bit seed (hex); winners = pickWinners(sorted ids, seed, winnersRequested)"},"winnersRequested":{"type":"integer"},"winnerUserIds":{"type":"array","items":{"type":"string"}},"replacesPrizeId":{"type":["string","null"]},"drawnBy":{"type":"string"},"note":{"type":["string","null"]},"drawnAt":{"type":"string","format":"date-time"},"campaignId":{"type":"string"},"eligible":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"detail":{"type":["string","null"]}},"required":["userId","detail"]}}},"required":["id","prize","kind","eligibleCount","eligibleHash","seed","winnersRequested","winnerUserIds","replacesPrizeId","drawnBy","note","drawnAt","campaignId","eligible"]},"prizes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"prize":{"type":"string","enum":["free_pro","trmnl"]},"userId":{"type":"string"},"status":{"type":"string","enum":["won","revoked"]},"drawId":{"type":"string"},"awardedAt":{"type":"string","format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"revokeReason":{"type":["string","null"]},"proStatus":{"type":["string","null"],"enum":["trialing","active"],"description":"The winner's Pro subscription now: trialing (extend the trial by a year in Polar), active (already paying), null (redeems 100% off at checkout)"},"campaignId":{"type":"string"}},"required":["id","prize","userId","status","drawId","awardedAt","revokedAt","revokeReason","proStatus","campaignId"]}}},"required":["draw","prizes"]},"CreateCampaignDraw":{"type":"object","properties":{"prize":{"type":"string","enum":["free_pro","trmnl"],"description":"free_pro (3 winners) or trmnl (1 TRMNL OG); runs once per prize"}},"required":["prize"]},"RedrawCampaignPrize":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500,"description":"Why the prize is revoked (e.g. no reply)"}},"required":["reason"]},"CreateTicketNote":{"type":"object","properties":{"actor":{"type":"string","enum":["team","agent"],"description":"`team` or `agent`"},"body":{"type":"string","minLength":1,"maxLength":20000,"description":"Internal note (Markdown)"},"agentRunId":{"type":"string","description":"Agent run the note belongs to (must belong to this ticket)"}},"required":["actor","body"]},"FinishTicketAgentRun":{"type":"object","properties":{"status":{"type":"string","enum":["completed","failed"],"description":"How the run ended"},"summary":{"type":"string","maxLength":2000,"description":"One-line outcome (e.g. \"asked for steps, waiting_customer\")"}},"required":["status"]},"FeedbackCategory":{"type":"string","enum":["feature","question"]},"FeedbackThreadStatus":{"type":"string","enum":["open","under_review","planned","in_progress","shipped","declined","answered","closed","merged"],"description":"Features: open, under_review, planned, in_progress, shipped, declined, merged. Questions: open, answered, closed, merged."},"FeedbackAuthor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["team"]},"ai":{"type":"boolean"}},"required":["kind","ai"]},{"type":"object","properties":{"kind":{"type":"string","enum":["member"]},"username":{"type":["string","null"]},"memberNumber":{"type":["integer","null"],"description":"Shown as \"Brewer #NNNN\" when there is no username"},"supporter":{"type":"boolean"}},"required":["kind","username","memberNumber","supporter"]},{"type":"object","properties":{"kind":{"type":"string","enum":["former"]}},"required":["kind"]}],"description":"Public identity. Never contains email or real name."},"FeedbackThreadListItem":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","description":"Global thread number (#118)"},"path":{"type":"string","description":"In-app path, e.g. /feedback/118-water-profile-import"},"title":{"type":"string"},"summaryExcerpt":{"type":["string","null"]},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"status":{"$ref":"#/components/schemas/FeedbackThreadStatus"},"labels":{"type":"array","items":{"type":"string"}},"onPublicRoadmap":{"type":"boolean"},"voteCount":{"type":"integer","description":"Distinct voters across the thread and threads merged into it"},"viewerHasVoted":{"type":"boolean"},"replyCount":{"type":"integer"},"author":{"$ref":"#/components/schemas/FeedbackAuthor"},"questionnaire":{"type":["string","null"],"enum":["wanted","answered"],"description":"Live questionnaire: `wanted` (the viewer has not answered), `answered`, or null (none live, or no viewer as in the admin API)"},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"},"lastMemberActivityAt":{"type":["string","null"],"format":"date-time","description":"Newest member activity: a published thread, reply or edit, an approved held post, a questionnaire answer. Not votes, not team/agent actions."}},"required":["id","number","path","title","summaryExcerpt","category","status","labels","onPublicRoadmap","voteCount","viewerHasVoted","replyCount","author","questionnaire","createdAt","lastActivityAt","lastMemberActivityAt"]},"FeedbackThreadListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackThreadListItem"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"FeedbackThreadRef":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"path":{"type":"string"}},"required":["id","number","path"]},"FeedbackCreateThreadResponse":{"allOf":[{"$ref":"#/components/schemas/FeedbackThreadRef"},{"type":"object","properties":{"skippedVoterUserIds":{"type":"array","items":{"type":"string"},"description":"voterUserIds that matched no user and were skipped"}},"required":["skippedVoterUserIds"]}]},"FeedbackStaffActor":{"type":"string","enum":["team","agent"],"description":"Who performs the change: `team` (Bernd) or `agent` (AI agent; posts get an AI label)."},"CreateFeedbackThread":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"title":{"type":"string","minLength":1,"maxLength":200},"body":{"type":"string","minLength":1,"maxLength":20000,"description":"Original post (Markdown subset, English)"},"summary":{"type":["string","null"],"maxLength":5000,"description":"Curated summary card (Markdown)"},"labels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"status":{"allOf":[{"$ref":"#/components/schemas/FeedbackThreadStatus"},{"description":"Initial status (default open)"}]},"statusReason":{"type":["string","null"],"maxLength":2000},"onPublicRoadmap":{"type":"boolean"},"authorUserId":{"type":["string","null"],"description":"Create on behalf of this user (migration). Omit for a team/agent thread."},"migratedFromTicket":{"type":"boolean","description":"Mark the original post as migrated from a support ticket"},"legacyRoadmapItemId":{"type":["string","null"],"description":"Roadmap item this thread replaces; a second thread for the same item returns 409"},"voterUserIds":{"type":"array","items":{"type":"string"},"maxItems":5000,"description":"Record one upvote per user (migration; feature threads only)"}},"required":["actor","category","title","body"]},"FeedbackPost":{"type":["object","null"],"properties":{"id":{"type":"string"},"actor":{"type":"string","enum":["user","team","agent","system"]},"author":{"$ref":"#/components/schemas/FeedbackAuthor"},"body":{"type":["string","null"],"description":"Markdown subset"},"deleted":{"type":"boolean"},"edited":{"type":"boolean"},"isOriginalPost":{"type":"boolean"},"isAcceptedAnswer":{"type":"boolean"},"migratedFromTicket":{"type":"boolean"},"moderationStatus":{"type":"string","enum":["published","held","rejected"]},"moderationReason":{"type":["string","null"],"description":"Reason code (insult, hate, sexual, spam, personal_data, off_topic, moderation_unavailable, needs_review, reported) or a moderator's text"},"pendingEdit":{"type":["object","null"],"properties":{"body":{"type":"string"},"moderationStatus":{"type":"string","enum":["published","held","rejected"]},"moderationReason":{"type":["string","null"]}},"required":["body","moderationStatus","moderationReason"],"description":"An author's edit that is held or was rejected; the published body stays visible"},"isOwn":{"type":"boolean"},"viewerReported":{"type":"boolean"},"hidden":{"type":"boolean","description":"Hidden by user reports until reviewed"},"score":{"type":"integer"},"viewerVote":{"type":"integer"},"collapsed":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","actor","author","body","deleted","edited","isOriginalPost","isAcceptedAnswer","migratedFromTicket","moderationStatus","moderationReason","pendingEdit","isOwn","viewerReported","hidden","score","viewerVote","collapsed","createdAt"]},"FeedbackEvent":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["status","status_date","title","summary","category","label","roadmap_flag","merged","unmerged","linked","unlinked","accepted_answer","brief"]},"actor":{"type":"string","enum":["user","team","agent","system"]},"author":{"$ref":"#/components/schemas/FeedbackAuthor"},"payload":{"type":"object","additionalProperties":{},"description":"Type-specific payload (from/to, revisionId, merge ids, link)"},"note":{"type":["string","null"]},"relatedThread":{"type":["object","null"],"properties":{"number":{"type":"integer"},"title":{"type":"string"},"path":{"type":"string"}},"required":["number","title","path"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","type","actor","author","payload","note","relatedThread","createdAt"]},"FeedbackMergedBlock":{"type":"object","properties":{"threadId":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"mergedAt":{"type":"string","format":"date-time"},"originalPost":{"$ref":"#/components/schemas/FeedbackPost"},"replies":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/FeedbackPost"},{"type":"object"}]}}},"required":["threadId","number","title","mergedAt","originalPost","replies"]},"FeedbackTimelineEntry":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["post"]},"at":{"type":"string","format":"date-time"},"post":{"allOf":[{"$ref":"#/components/schemas/FeedbackPost"},{"type":"object"}]}},"required":["kind","at","post"]},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"at":{"type":"string","format":"date-time"},"event":{"$ref":"#/components/schemas/FeedbackEvent"}},"required":["kind","at","event"]},{"type":"object","properties":{"kind":{"type":"string","enum":["merged"]},"at":{"type":"string","format":"date-time"},"block":{"$ref":"#/components/schemas/FeedbackMergedBlock"}},"required":["kind","at","block"]}]},"FeedbackLink":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["thread","github","changelog"]},"direction":{"type":"string","enum":["outgoing","incoming"],"description":"outgoing: stored on this thread (remove it here). incoming: a thread link stored on the linked thread or on a thread merged into this one (remove it there)."},"url":{"type":["string","null"]},"title":{"type":["string","null"]},"thread":{"type":["object","null"],"properties":{"number":{"type":"integer"},"title":{"type":"string"},"status":{"$ref":"#/components/schemas/FeedbackThreadStatus"},"path":{"type":"string"}},"required":["number","title","status","path"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","type","direction","url","title","thread","createdAt"]},"FeedbackSummaryRevision":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":["string","null"]},"actor":{"type":"string","enum":["user","team","agent","system"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","summary","actor","createdAt"]},"FeedbackBriefRevision":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["internal","public"]},"body":{"type":["string","null"]},"briefCommit":{"type":["string","null"]},"actor":{"type":"string","enum":["user","team","agent","system"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","kind","body","briefCommit","actor","createdAt"]},"FeedbackThreadDetail":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"path":{"type":"string"},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"status":{"$ref":"#/components/schemas/FeedbackThreadStatus"},"statusReason":{"type":["string","null"]},"statusChangedAt":{"type":["string","null"],"format":"date-time"},"title":{"type":"string"},"originalTitle":{"type":"string"},"summary":{"type":["string","null"]},"summaryUpdatedAt":{"type":["string","null"],"format":"date-time"},"publicBrief":{"type":["string","null"],"description":"\"How this could work\" for members (Markdown). Not a commitment."},"publicBriefUpdatedAt":{"type":["string","null"],"format":"date-time"},"publicBriefByAgent":{"type":"boolean","description":"The current public brief was written by the agent (AI label)"},"internalBrief":{"type":["string","null"],"description":"Admin only (Markdown): never shown to members"},"internalBriefUpdatedAt":{"type":["string","null"],"format":"date-time"},"briefCommit":{"type":["string","null"],"description":"Git SHA of main the briefs were written against"},"labels":{"type":"array","items":{"type":"string"}},"onPublicRoadmap":{"type":"boolean"},"moderationStatus":{"type":"string","enum":["published","held","rejected"]},"mergedInto":{"type":["object","null"],"properties":{"id":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"path":{"type":"string"}},"required":["id","number","title","path"]},"migratedFromTicket":{"type":"boolean"},"legacyRoadmapItemId":{"type":["string","null"]},"acceptedAnswerPostId":{"type":["string","null"]},"author":{"$ref":"#/components/schemas/FeedbackAuthor"},"voteCount":{"type":"integer"},"viewerHasVoted":{"type":"boolean"},"viewerIsAuthor":{"type":"boolean"},"viewerSubscribed":{"type":"boolean"},"originalPost":{"$ref":"#/components/schemas/FeedbackPost"},"acceptedAnswer":{"$ref":"#/components/schemas/FeedbackPost"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackTimelineEntry"}},"links":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackLink"},"description":"All links, including admin-only GitHub links"},"summaryRevisions":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackSummaryRevision"}},"briefRevisions":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackBriefRevision"}},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"},"lastMemberActivityAt":{"type":["string","null"],"format":"date-time"}},"required":["id","number","path","category","status","statusReason","statusChangedAt","title","originalTitle","summary","summaryUpdatedAt","publicBrief","publicBriefUpdatedAt","publicBriefByAgent","internalBrief","internalBriefUpdatedAt","briefCommit","labels","onPublicRoadmap","moderationStatus","mergedInto","migratedFromTicket","legacyRoadmapItemId","acceptedAnswerPostId","author","voteCount","viewerHasVoted","viewerIsAuthor","viewerSubscribed","originalPost","acceptedAnswer","timeline","links","summaryRevisions","briefRevisions","createdAt","lastActivityAt","lastMemberActivityAt"]},"UpdateFeedbackThreadResponse":{"allOf":[{"$ref":"#/components/schemas/FeedbackThreadRef"},{"type":"object","properties":{"changed":{"type":"array","items":{"type":"string"}}},"required":["changed"]}]},"UpdateFeedbackThread":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"title":{"type":"string","minLength":1,"maxLength":200},"summary":{"type":["string","null"],"maxLength":5000,"description":"New summary (null clears). Every change is kept as a revision."},"status":{"allOf":[{"$ref":"#/components/schemas/FeedbackThreadStatus"},{"description":"Not `merged` (use the merge endpoint) or `answered` (use accepted-answer)"}]},"statusReason":{"type":["string","null"],"maxLength":2000,"description":"Public reason (required for declined) or optional note. Omit to keep the current reason, also when only `status` changes; `null` clears it. Can be sent without `status` to edit the reason."},"labels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20,"description":"Full label set (replaces the current labels)"},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"onPublicRoadmap":{"type":"boolean"},"statusChangedAt":{"type":"string","description":"When the status was reached (ISO timestamp, not in the future), e.g. to backfill migrated threads. Applies to the status set in this request, else to the current status (recorded as a `status_date` event, no notification). Default: now when the status changes.","format":"date-time"},"internalBrief":{"type":["string","null"],"maxLength":50000,"description":"Admin-only feature brief (Markdown). Never shown to members, no timeline event. Kept as a revision; null clears."},"publicBrief":{"type":["string","null"],"maxLength":10000,"description":"\"How this could work\" for members (Markdown, plain language, no dates or commitments). Kept as a revision; a `brief` timeline event, no notification. null clears."},"briefCommit":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{7,40}$","description":"Git SHA of main the briefs were written against"}},"required":["actor"]},"FeedbackPostCreated":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","createdAt"]},"CreateFeedbackPost":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"body":{"type":"string","minLength":1,"maxLength":20000,"description":"Markdown subset, English. Not moderated."},"authorUserId":{"type":["string","null"],"minLength":1,"description":"Credit the post to this user (migration): shown as the user, subscribed as a commenter. 400 if the user does not exist."},"migratedFromTicket":{"type":"boolean","description":"Show \"migrated from a support ticket\" on the post"}},"required":["actor","body"]},"FeedbackParticipantsResult":{"type":"object","properties":{"addedVotes":{"type":"integer","description":"New votes (existing ones are no-ops)"},"addedSubscriptions":{"type":"integer","description":"New subscriptions (existing ones, incl. unsubscribed, are no-ops)"},"skippedUserIds":{"type":"array","items":{"type":"string"},"description":"Ids that matched no user"}},"required":["addedVotes","addedSubscriptions","skippedUserIds"]},"AddFeedbackParticipants":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"voterUserIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":5000,"description":"Record one migration upvote per user (feature threads; also when voting is frozen). Voters are subscribed too."},"subscriberUserIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":5000,"description":"Subscribe these users. Users who unsubscribed before are not re-added."}},"required":["actor"]},"FeedbackAcceptedAnswerResponse":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/FeedbackThreadStatus"}},"required":["status"]},"SetFeedbackAcceptedAnswer":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"postId":{"type":["string","null"],"description":"Reply to accept, or null to clear"}},"required":["actor","postId"]},"FeedbackMergeResponse":{"type":"object","properties":{"sourceId":{"type":"string"},"targetId":{"type":"string"},"status":{"$ref":"#/components/schemas/FeedbackThreadStatus"}},"required":["sourceId","targetId"]},"MergeFeedbackThread":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"target":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"string","minLength":1}],"description":"Target thread number or id"},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Public reason shown on both threads"}},"required":["actor","target","reason"]},"UnmergeFeedbackThread":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"note":{"type":["string","null"],"maxLength":2000}},"required":["actor"]},"FeedbackLinkCreated":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"AddFeedbackLink":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"type":{"type":"string","enum":["thread","github","changelog"],"description":"thread (visible), github (admin only), changelog (visible)"},"target":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"string","minLength":1}],"description":"Related thread number or id (type thread)"},"url":{"type":"string","format":"uri","description":"GitHub issue/PR URL (type github) or changelog URL"},"changelogId":{"type":"string","description":"Changelog entry id (type changelog)"},"title":{"type":"string","maxLength":200}},"required":["actor","type"]},"FeedbackDuplicateSuggestion":{"type":"object","properties":{"id":{"type":"string"},"threadId":{"type":"string"},"duplicateOfThreadId":{"type":"string"},"suggestedByUserId":{"type":["string","null"]},"note":{"type":["string","null"]},"status":{"type":"string","enum":["open","accepted","dismissed"]},"createdAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"thread":{"type":["object","null"],"properties":{"id":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"}},"required":["id","number","title"]},"duplicateOf":{"type":["object","null"],"properties":{"id":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"}},"required":["id","number","title"]}},"required":["id","threadId","duplicateOfThreadId","suggestedByUserId","note","status","createdAt","resolvedAt","thread","duplicateOf"]},"FeedbackDuplicateSuggestionListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackDuplicateSuggestion"}}},"required":["data"]},"FeedbackModerationQueueItem":{"type":"object","properties":{"postId":{"type":"string"},"kind":{"type":"string","enum":["post","edit","reported"],"description":"post: a new thread or reply. edit: an author's edit. reported: hidden after reports."},"thread":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"path":{"type":"string"},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"moderationStatus":{"type":"string","enum":["published","held","rejected"]}},"required":["id","number","title","path","category","moderationStatus"]},"isOriginalPost":{"type":"boolean","description":"Approving or rejecting the original post publishes or rejects the whole thread"},"author":{"type":"object","properties":{"userId":{"type":["string","null"]},"username":{"type":["string","null"]},"memberNumber":{"type":["integer","null"]}},"required":["userId","username","memberNumber"]},"body":{"type":"string","description":"Post body. For edits: the currently published body."},"pendingBody":{"type":["string","null"],"description":"The edit waiting for review (kind edit)"},"moderationStatus":{"type":"string","enum":["published","held","rejected"]},"moderationReason":{"type":["string","null"]},"moderatedBy":{"type":["string","null"],"description":"`ai:<model>`, `rule:<name>`, `team` or `agent`"},"reports":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["insult","hate","sexual","spam","personal_data","off_topic","other"]},"details":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["reason","details","createdAt"]}},"hiddenAt":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["postId","kind","thread","isOriginalPost","author","body","pendingBody","moderationStatus","moderationReason","moderatedBy","reports","hiddenAt","submittedAt","createdAt"]},"FeedbackModerationQueueResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackModerationQueueItem"}}},"required":["data"]},"ReviewFeedbackModerationResponse":{"type":"object","properties":{"postId":{"type":"string"},"kind":{"type":"string","enum":["post","edit","reported"]},"moderationStatus":{"type":"string","enum":["published","held","rejected"]}},"required":["postId","kind","moderationStatus"]},"ReviewFeedbackModeration":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"action":{"type":"string","enum":["approve","reject"],"description":"approve: publish the post or edit, or keep a reported post. reject: reject the post or edit, or remove a reported post."},"reason":{"type":["string","null"],"maxLength":500,"description":"Shown to the author when rejecting"}},"required":["actor","action"]},"FeedbackQuestionnaireResults":{"type":["object","null"],"properties":{"respondents":{"type":"integer"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"multiple":{"type":"boolean"},"allowOther":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer"},"share":{"type":"number"}},"required":["id","label","count","share"]}},"otherCount":{"type":"integer"},"otherShare":{"type":"number"},"otherTexts":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"moderationStatus":{"type":"string","enum":["published","held","rejected"]},"responseId":{"type":"string","description":"Review held texts with POST /questionnaires/:id/responses/:responseId"},"updatedAt":{"type":"string","format":"date-time"}},"required":["text"]},"description":"Admin API: every \"Other\" text with its moderation status and response id, newest first"}},"required":["id","text","multiple","allowOther","options","otherCount","otherShare","otherTexts"]}}},"required":["respondents","questions"]},"FeedbackImplementationContext":{"type":"object","properties":{"thread":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"path":{"type":"string"},"category":{"$ref":"#/components/schemas/FeedbackCategory"},"status":{"$ref":"#/components/schemas/FeedbackThreadStatus"},"statusReason":{"type":["string","null"]},"statusChangedAt":{"type":["string","null"],"format":"date-time"},"title":{"type":"string"},"originalTitle":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}},"onPublicRoadmap":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"},"lastMemberActivityAt":{"type":["string","null"],"format":"date-time"}},"required":["id","number","path","category","status","statusReason","statusChangedAt","title","originalTitle","labels","onPublicRoadmap","createdAt","lastActivityAt","lastMemberActivityAt"]},"summary":{"type":["string","null"]},"brief":{"type":"object","properties":{"internal":{"type":["string","null"]},"internalUpdatedAt":{"type":["string","null"],"format":"date-time"},"public":{"type":["string","null"]},"publicUpdatedAt":{"type":["string","null"],"format":"date-time"},"publicByAgent":{"type":"boolean"},"commit":{"type":["string","null"],"description":"Git SHA of main the briefs were written against: diff it against current main"}},"required":["internal","internalUpdatedAt","public","publicUpdatedAt","publicByAgent","commit"]},"questionnaires":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","live","closed"]},"title":{"type":"string"},"intro":{"type":["string","null"]},"createdByAgent":{"type":"boolean"},"openedAt":{"type":["string","null"],"format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"respondents":{"type":"integer"},"results":{"$ref":"#/components/schemas/FeedbackQuestionnaireResults"}},"required":["id","status","title","intro","createdByAgent","openedAt","closedAt","respondents","results"]}},"originalPost":{"type":["object","null"],"additionalProperties":{}},"replies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threadNumber":{"type":"integer","description":"The thread the post was written on (a merged-in thread for merged blocks)"},"actor":{"type":"string","enum":["user","team","agent","system"]},"author":{"$ref":"#/components/schemas/FeedbackAuthor"},"body":{"type":["string","null"]},"isOriginalPost":{"type":"boolean"},"score":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","threadNumber","actor","author","body","isOriginalPost","score","createdAt"]},"description":"Published replies, including the posts of merged-in threads"},"links":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackLink"}},"statusHistory":{"type":"array","items":{"type":"object","properties":{"actor":{"type":"string","enum":["user","team","agent","system"]},"payload":{"type":"object","additionalProperties":{}},"note":{"type":["string","null"]},"relatedThread":{"type":["object","null"],"properties":{"number":{"type":"integer"},"title":{"type":"string"},"path":{"type":"string"}},"required":["number","title","path"]},"createdAt":{"type":"string","format":"date-time"}},"required":["actor","payload","note","relatedThread","createdAt"]}},"votes":{"type":"object","properties":{"voters":{"type":"integer","description":"Distinct voters on the thread and threads merged into it (the public count)"},"total":{"type":"integer","description":"Vote rows, incl. a member's second vote on a merged-in duplicate"},"onThread":{"type":"integer"}},"required":["voters","total","onThread"]}},"required":["thread","summary","brief","questionnaires","originalPost","replies","links","statusHistory","votes"]},"FeedbackQuestionnaireQuestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"text":{"type":"string","minLength":1,"maxLength":300},"multiple":{"type":"boolean","default":false},"allowOther":{"type":"boolean","default":true},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,39}$"},"label":{"type":"string","minLength":1,"maxLength":120}},"required":["id","label"]},"minItems":2,"maxItems":4}},"required":["id","text","options"]},"minItems":3,"maxItems":6,"description":"3-6 questions. Each: stable `id` (lowercase, digits, - or _), `text`, `multiple` (default false), `allowOther` (default true: an \"Other\" option with free text), and 2-4 `options` with stable ids. Ids never change once the questionnaire is live: answers reference them."},"FeedbackQuestionnaireResponse":{"type":"object","properties":{"id":{"type":"string"},"author":{"$ref":"#/components/schemas/FeedbackAuthor"},"answers":{"type":"object","additionalProperties":{"type":"object","properties":{"optionIds":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":4},"other":{"type":["string","null"],"maxLength":500}},"required":["optionIds"]}},"moderationStatus":{"type":"string","enum":["published","held","rejected"]},"moderationReason":{"type":["string","null"]},"submittedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","author","answers","moderationStatus","moderationReason","submittedAt","updatedAt"]},"FeedbackQuestionnaire":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","live","closed"]},"title":{"type":"string"},"intro":{"type":["string","null"]},"questions":{"$ref":"#/components/schemas/FeedbackQuestionnaireQuestions"},"createdByAgent":{"type":"boolean"},"openedAt":{"type":["string","null"],"format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"respondents":{"type":"integer"},"results":{"$ref":"#/components/schemas/FeedbackQuestionnaireResults"},"responses":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FeedbackQuestionnaireResponse"}}},"required":["id","status","title","intro","questions","createdByAgent","openedAt","closedAt","createdAt","respondents","results","responses"]},"FeedbackQuestionnaireListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackQuestionnaire"}}},"required":["data"]},"FeedbackQuestionnaireWriteResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","live","closed"]},"changed":{"type":"array","items":{"type":"string"}},"closedQuestionnaireId":{"type":["string","null"],"description":"The live questionnaire that opening this one closed"}},"required":["id"]},"CreateFeedbackQuestionnaire":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"title":{"type":"string","minLength":1,"maxLength":200},"intro":{"type":["string","null"],"maxLength":1000,"description":"One or two sentences shown above the first question"},"questions":{"$ref":"#/components/schemas/FeedbackQuestionnaireQuestions"},"open":{"type":"boolean","description":"Open right away (closes the thread's current live questionnaire). Default: draft."}},"required":["actor","title","questions"]},"FeedbackQuestionnaireSummary":{"type":"object","properties":{"id":{"type":"string"},"thread":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"path":{"type":"string"},"status":{"$ref":"#/components/schemas/FeedbackThreadStatus"}},"required":["id","number","title","path","status"]},"status":{"type":"string","enum":["draft","live","closed"]},"title":{"type":"string"},"createdByAgent":{"type":"boolean"},"questionCount":{"type":"integer"},"responseCount":{"type":"integer"},"newResponseCount":{"type":"integer","description":"Responses submitted or changed since answeredSince (all without it)"},"lastResponseAt":{"type":["string","null"],"format":"date-time"},"heldOtherCount":{"type":"integer","description":"Responses whose \"Other\" texts wait for review"},"openedAt":{"type":["string","null"],"format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","thread","status","title","createdByAgent","questionCount","responseCount","newResponseCount","lastResponseAt","heldOtherCount","openedAt","closedAt","createdAt"]},"FeedbackQuestionnaireSummaryListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackQuestionnaireSummary"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"UpdateFeedbackQuestionnaire":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"title":{"type":"string","minLength":1,"maxLength":200},"intro":{"type":["string","null"],"maxLength":1000},"questions":{"$ref":"#/components/schemas/FeedbackQuestionnaireQuestions"}},"required":["actor"]},"FeedbackQuestionnaireAction":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"}},"required":["actor"]},"FeedbackQuestionnaireResultsResponse":{"type":"object","properties":{"questionnaire":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","live","closed"]},"title":{"type":"string"},"intro":{"type":["string","null"]},"questions":{"$ref":"#/components/schemas/FeedbackQuestionnaireQuestions"},"createdByAgent":{"type":"boolean"},"openedAt":{"type":["string","null"],"format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"threadNumber":{"type":"integer"}},"required":["id","status","title","intro","questions","createdByAgent","openedAt","closedAt","createdAt","threadNumber"]},"results":{"allOf":[{"$ref":"#/components/schemas/FeedbackQuestionnaireResults"},{"type":"object","description":"Complete totals, also with answeredSince"}]},"answeredSince":{"type":["string","null"],"format":"date-time"},"responses":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackQuestionnaireResponse"},"description":"Each member's answers (display identity only), filtered by answeredSince"}},"required":["questionnaire","results","answeredSince","responses"]},"ReviewFeedbackQuestionnaireResponse":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/FeedbackStaffActor"},"action":{"type":"string","enum":["approve","reject"],"description":"approve: show the \"Other\" texts to members. reject: hide them. Picked options count either way."},"reason":{"type":["string","null"],"maxLength":500}},"required":["actor","action"]}},"parameters":{}},"paths":{"/api/v1/brews":{"get":{"summary":"List brews","description":"Get a paginated list of brews for the authenticated user","tags":["Brews"],"security":[{"bearerAuth":["brews:read"]}],"parameters":[{"schema":{"type":"integer","description":"Current page number"},"required":true,"name":"page","in":"query"},{"schema":{"type":"integer","description":"Items per page"},"required":true,"name":"limit","in":"query"},{"schema":{"$ref":"#/components/schemas/BrewStatus"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List of brews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrewListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create brew","description":"Create a new brew","tags":["Brews"],"security":[{"bearerAuth":["brews:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBrew"}}}},"responses":{"201":{"description":"Brew created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brew"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/brews/{id}":{"get":{"summary":"Get brew","description":"Get a specific brew by ID","tags":["Brews"],"security":[{"bearerAuth":["brews:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Brew details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brew"}}}},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update brew","description":"Partially update an existing brew","tags":["Brews"],"security":[{"bearerAuth":["brews:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBrew"}}}},"responses":{"200":{"description":"Updated brew","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brew"}}}},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete brew","description":"Delete a brew","tags":["Brews"],"security":[{"bearerAuth":["brews:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Brew deleted"},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/brews/{id}/custom-fields":{"get":{"summary":"Get Custom Field values by key","description":"Get effective Brew Custom Field values and matching Brew Notes for up to 100 comma-separated keys. Archived fields remain resolvable.","tags":["Custom Fields"],"security":[{"bearerAuth":["brews:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Comma-separated Custom Field keys (maximum 100 unique keys)","example":"lab-report-url,fermenter-number"},"required":true,"name":"keys","in":"query"}],"responses":{"200":{"description":"Effective Custom Field values and matching Brew Notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomFieldLookupResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/brews/{id}/notes":{"get":{"summary":"List brew notes","description":"Get a paginated list of notes for a brew","tags":["Brews"],"security":[{"bearerAuth":["brews:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrewNoteListResponse"}}}},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Add brew note","description":"Add a note to a brew","tags":["Brews"],"security":[{"bearerAuth":["brews:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBrewNote"}}}},"responses":{"201":{"description":"Note added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrewNote"}}}},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/brews/{id}/notes/{noteId}":{"get":{"summary":"Get brew note","description":"Get a specific note from a brew","tags":["Brews"],"security":[{"bearerAuth":["brews:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Note ID"},"required":true,"name":"noteId","in":"path"}],"responses":{"200":{"description":"Note details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrewNote"}}}},"404":{"description":"Brew or note not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update brew note","description":"Update a specific note on a brew","tags":["Brews"],"security":[{"bearerAuth":["brews:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Note ID"},"required":true,"name":"noteId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBrewNote"}}}},"responses":{"200":{"description":"Updated note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrewNote"}}}},"404":{"description":"Brew or note not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete brew note","description":"Delete a specific note from a brew","tags":["Brews"],"security":[{"bearerAuth":["brews:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Note ID"},"required":true,"name":"noteId","in":"path"}],"responses":{"204":{"description":"Note deleted"},"404":{"description":"Brew or note not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/brews/{id}/readings":{"get":{"summary":"List fermentation readings","description":"Get fermentation readings for a brew, paginated with the most recent first","tags":["Brews"],"security":[{"bearerAuth":["brews:read"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated list of fermentation readings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FermentationReadingListResponse"}}}},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Add fermentation reading","description":"Add a fermentation reading (gravity, temperature, pH, pressure) to a brew","tags":["Brews"],"security":[{"bearerAuth":["brews:write"]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Brew ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFermentationReading"}}}},"responses":{"201":{"description":"Reading added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FermentationReading"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brew not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory":{"get":{"summary":"List all inventory","description":"Get all inventory items grouped by type (fermentables, hops, yeasts, miscs). Consider using type-specific endpoints for pagination.","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"responses":{"200":{"description":"Inventory items grouped by type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/fermentables":{"get":{"summary":"List fermentable inventory","description":"Get a paginated list of fermentable inventory items","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of fermentables","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryFermentableListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create fermentable inventory item","description":"Add a fermentable to inventory. Auto-merges if same ingredientId already exists.","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryFermentable"}}}},"responses":{"200":{"description":"Merged with existing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryFermentable"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryFermentable"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/hops":{"get":{"summary":"List hop inventory","description":"Get a paginated list of hop inventory items","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of hops","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryHopListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create hop inventory item","description":"Add a hop to inventory. Auto-merges if same ingredientId already exists.","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryHop"}}}},"responses":{"200":{"description":"Merged with existing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryHop"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryHop"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/yeasts":{"get":{"summary":"List yeast inventory","description":"Get a paginated list of yeast inventory items","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of yeasts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryYeastListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create yeast inventory item","description":"Add a yeast to inventory. Auto-merges if same ingredientId already exists.","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryYeast"}}}},"responses":{"200":{"description":"Merged with existing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryYeast"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryYeast"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/miscs":{"get":{"summary":"List misc inventory","description":"Get a paginated list of miscellaneous inventory items","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of misc items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMiscListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create misc inventory item","description":"Add a misc item to inventory. Auto-merges if same ingredientId already exists.","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInventoryMisc"}}}},"responses":{"200":{"description":"Merged with existing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMisc"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMisc"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/fermentables/{id}":{"get":{"summary":"Get fermentable inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Item details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryFermentable"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update fermentable inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryFermentable"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryFermentable"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete fermentable inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/hops/{id}":{"get":{"summary":"Get hop inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Item details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryHop"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update hop inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryHop"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryHop"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete hop inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/yeasts/{id}":{"get":{"summary":"Get yeast inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Item details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryYeast"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update yeast inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryYeast"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryYeast"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete yeast inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/inventory/miscs/{id}":{"get":{"summary":"Get misc inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:read"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Item details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMisc"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update misc inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInventoryMisc"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryMisc"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete misc inventory item","tags":["Inventory"],"security":[{"bearerAuth":["inventory:write"]}],"parameters":[{"schema":{"type":"string","description":"Inventory item ID"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/equipment":{"get":{"summary":"List equipment profiles","description":"Get all equipment profiles for the authenticated user","tags":["Profiles"],"security":[{"bearerAuth":["equipment:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of equipment profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create equipment profile","tags":["Profiles"],"security":[{"bearerAuth":["equipment:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEquipmentProfile"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentProfile"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/equipment/{id}":{"get":{"summary":"Get equipment profile","tags":["Profiles"],"security":[{"bearerAuth":["equipment:read"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Equipment profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentProfile"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update equipment profile","tags":["Profiles"],"security":[{"bearerAuth":["equipment:write"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEquipmentProfile"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquipmentProfile"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete equipment profile","tags":["Profiles"],"security":[{"bearerAuth":["equipment:write"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/styles":{"get":{"summary":"List style profiles","description":"Get all beer style profiles for the authenticated user","tags":["Profiles"],"security":[{"bearerAuth":["styles:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of style profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create style profile","tags":["Profiles"],"security":[{"bearerAuth":["styles:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStyleProfile"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleProfile"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/styles/{id}":{"get":{"summary":"Get style profile","tags":["Profiles"],"security":[{"bearerAuth":["styles:read"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Style profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleProfile"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update style profile","tags":["Profiles"],"security":[{"bearerAuth":["styles:write"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStyleProfile"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleProfile"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete style profile","tags":["Profiles"],"security":[{"bearerAuth":["styles:write"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/mash":{"get":{"summary":"List mash profiles","tags":["Profiles"],"security":[{"bearerAuth":["profiles:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of mash profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MashProfileListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/mash/{id}":{"get":{"summary":"Get mash profile","tags":["Profiles"],"security":[{"bearerAuth":["profiles:read"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Mash profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MashProfileResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/fermentation":{"get":{"summary":"List fermentation profiles","tags":["Profiles"],"security":[{"bearerAuth":["profiles:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of fermentation profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FermentationProfileListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/fermentation/{id}":{"get":{"summary":"Get fermentation profile","tags":["Profiles"],"security":[{"bearerAuth":["profiles:read"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Fermentation profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FermentationProfileResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/water":{"get":{"summary":"List water profiles","tags":["Profiles"],"security":[{"bearerAuth":["profiles:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of water profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaterProfileListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/profiles/water/{id}":{"get":{"summary":"Get water profile","tags":["Profiles"],"security":[{"bearerAuth":["profiles:read"]}],"parameters":[{"schema":{"type":"string","description":"Profile ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Water profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaterProfileResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/custom-fields":{"get":{"summary":"List custom field definitions","description":"Get all custom field definitions. Optional ?stage= filter.","tags":["Custom Fields"],"security":[{"bearerAuth":["custom-fields:read"]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of custom field definitions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomFieldDefinitionListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (missing scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/custom-fields/{id}":{"get":{"summary":"Get custom field definition","tags":["Custom Fields"],"security":[{"bearerAuth":["custom-fields:read"]}],"parameters":[{"schema":{"type":"string","description":"Field definition ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Custom field definition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomFieldDefinition"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/campaigns/{id}":{"get":{"summary":"Get campaign draw overview","description":"Dates, participant counts, the eligible lists of the free-Pro and TRMNL OG draws (TRMNL OG billing countries are asked from Polar), recorded draws and prizes.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","example":"advent-2026"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"false skips the Polar billing-country lookups (default true)"},"required":false,"name":"includeTrmnl","in":"query"}],"responses":{"200":{"description":"Campaign overview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignOverview"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/campaigns/{id}/draws":{"post":{"summary":"Draw campaign prize winners","description":"Runs the one initial draw of a prize with a fresh random seed and stores eligible list, hash, seed and winners. Free-Pro winners get 100% off their first Pro year.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","example":"advent-2026"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaignDraw"}}}},"responses":{"201":{"description":"Recorded draw","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDrawResult"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Too early, already drawn, nobody eligible, or Polar lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/campaigns/{id}/prizes/{prizeId}/redraw":{"post":{"summary":"Revoke a prize and redraw","description":"Revokes one prize (with a reason) and draws one replacement among everyone still eligible who never held it. Both are recorded.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","example":"advent-2026"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"prizeId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedrawCampaignPrize"}}}},"responses":{"201":{"description":"Recorded redraw","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDrawResult"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown campaign or prize","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Prize already revoked, nobody eligible, or Polar lookup failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/tickets":{"get":{"summary":"List admin tickets","description":"Get a paginated list of feedback tickets for admin workflows.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["new","acked","in_progress","waiting_customer","resolved","wontfix","reopened","added_to_external","new_reopened","all"],"description":"Filter by status; new_reopened matches the screen's New+Reopened view"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["minor","medium","blocking"],"description":"Filter by bug severity"},"required":false,"name":"severity","in":"query"},{"schema":{"type":["boolean","null"],"default":true},"required":false,"name":"hideDone","in":"query"},{"schema":{"type":["integer","null"],"minimum":1},"required":false,"name":"staleDays","in":"query"},{"schema":{"type":"string","description":"Filter by milestone ID"},"required":false,"name":"milestoneId","in":"query"},{"schema":{"type":"string","enum":["exclude","only","all"],"default":"exclude","description":"Tickets held by AI triage as spam: hidden by default (`exclude`), `only` lists them, `all` includes them"},"required":false,"name":"held","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of tickets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create admin ticket","tags":["Admin"],"security":[{"adminApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTicket"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/tickets/stats":{"get":{"summary":"Get admin ticket stats","tags":["Admin"],"security":[{"adminApiKey":[]}],"responses":{"200":{"description":"Ticket dashboard stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketStats"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/tickets/{id}":{"get":{"summary":"Get admin ticket","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Ticket detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetailResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update admin ticket","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTicket"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/tickets/{id}/messages":{"get":{"summary":"List admin ticket messages","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Ticket message thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketMessageListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Reply to admin ticket","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyToTicket"}}}},"responses":{"201":{"description":"Reply sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketReplyResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/tickets/{id}/notes":{"post":{"summary":"Add internal ticket note","description":"Internal note, never shown to the customer. The bug agent leaves one per run (`actor: agent`).","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTicketNote"}}}},"responses":{"201":{"description":"Note added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketNote"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/tickets/{id}/agent-runs/{runId}":{"patch":{"summary":"Finish bug agent run","description":"The bug agent reports its run as completed or failed, so a later customer reply can start a new run.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Ticket UUID or numeric short ID","example":"42"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Agent run ID (the `run:` line of the dispatch payload)"},"required":true,"name":"runId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinishTicketAgentRun"}}}},"responses":{"200":{"description":"Run finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketAgentRun"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Ticket or in-flight run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads":{"get":{"summary":"List feedback threads","description":"Feature requests and questions in every moderation state. Merged threads are excluded unless includeMerged=true.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/FeedbackCategory"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","description":"Comma-separated statuses, e.g. `planned,in_progress`"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["top","trending","new","active","member_active"],"default":"top","description":"top (votes), trending (votes in the last 30 days), new, active (any activity), member_active (newest member activity first; threads without member activity last)"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","description":"Only threads with member activity at or after this time (`lastMemberActivityAt`): published threads, replies and edits, approved held posts, questionnaire answers. Not votes, not team/agent actions.","format":"date-time"},"required":false,"name":"memberActivitySince","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"onPublicRoadmap","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"includeMerged","in":"query"},{"schema":{"type":"string","description":"Case-insensitive title search"},"required":false,"name":"q","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Threads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackThreadListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create feedback thread","description":"Create a team/agent thread, or a thread on behalf of a user (`authorUserId`, migration). Admin API content is not moderated. The author and voters are subscribed.","tags":["Admin"],"security":[{"adminApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFeedbackThread"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackCreateThreadResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Roadmap item already migrated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}":{"get":{"summary":"Get feedback thread","description":"Full thread with timeline, merged blocks, all links (incl. GitHub), held posts, the internal brief, and summary and brief revisions.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackThreadDetail"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Curate feedback thread","description":"Change title, summary, status (+ reason), labels, category, the public roadmap flag or the briefs (`internalBrief` admin only, `publicBrief`, `briefCommit`). Each public change is a timeline event; declined requires a reason; status changes notify subscribers, brief changes do not.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFeedbackThread"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFeedbackThreadResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/posts":{"post":{"summary":"Post team, agent or migrated reply","description":"Not moderated. Agent posts show the team badge plus an AI label. With `authorUserId` the post is credited to that user (migration) and the user is subscribed.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFeedbackPost"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackPostCreated"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/participants":{"post":{"summary":"Add migration votes and subscribers","description":"Idempotent: existing votes and subscriptions are no-ops, users who unsubscribed are not re-added, unknown ids are skipped and listed. Votes are recorded even when voting is frozen.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFeedbackParticipants"}}}},"responses":{"200":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackParticipantsResult"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/accepted-answer":{"post":{"summary":"Mark accepted answer","description":"Questions only. postId null clears the answer. Sets the status to answered (or back to open).","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFeedbackAcceptedAnswer"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackAcceptedAnswerResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/merge":{"post":{"summary":"Merge feedback thread","description":"Merge this thread into `target`. Non-destructive: the source keeps its posts, gets status merged and redirects to the target; votes count distinct users across both; subscribers move. No notifications.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeFeedbackThread"}}}},"responses":{"200":{"description":"Merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackMergeResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/unmerge":{"post":{"summary":"Unmerge feedback thread","description":"Reverse a merge and restore the thread's previous status.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnmergeFeedbackThread"}}}},"responses":{"200":{"description":"Unmerged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackMergeResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/links":{"post":{"summary":"Add feedback link","description":"Link a related thread (visible), a GitHub issue/PR (admin only) or a changelog entry (visible).","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFeedbackLink"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackLinkCreated"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Link already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/links/{linkId}":{"delete":{"summary":"Remove feedback link","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number or id","example":"118"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Link id"},"required":true,"name":"linkId","in":"path"},{"schema":{"$ref":"#/components/schemas/FeedbackStaffActor"},"required":true,"name":"actor","in":"query"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackLinkCreated"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/duplicate-suggestions":{"get":{"summary":"List duplicate suggestions","description":"\"Duplicate of #…\" suggestions from users, for the feedback agent.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["open","accepted","dismissed","all"],"default":"open"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackDuplicateSuggestionListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/moderation":{"get":{"summary":"List the moderation queue","description":"Member posts and edits the classifier held (or rejected), and posts hidden after 3 user reports. Oldest first.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["open","held","hidden","rejected"],"default":"open","description":"open: held + hidden (default). held: new posts and edits waiting for review. hidden: hidden after 3 user reports. rejected: rejected posts (to undo false positives)."},"required":false,"name":"state","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Queue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackModerationQueueResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/moderation/{postId}":{"post":{"summary":"Review a moderation queue item","description":"Approve or reject a held post, a held edit or a report-hidden post. Deciding an original post publishes or rejects its thread. Approving a reply notifies the thread's subscribers.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Post id"},"required":true,"name":"postId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewFeedbackModeration"}}}},"responses":{"200":{"description":"Reviewed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewFeedbackModerationResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/implementation-context":{"get":{"summary":"Get implementation context","description":"Everything an implementing agent needs in one call: thread, summary, internal and public brief (with briefCommit), all questionnaires with totals and free-text answers, published replies (incl. merged-in threads), links, status history and votes.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackImplementationContext"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/threads/{id}/questionnaires":{"get":{"summary":"List thread questionnaires","description":"Every questionnaire of the thread (drafts too), newest first, with totals and each member's answers.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Questionnaires","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create questionnaire","description":"3-6 questions with 2-4 options each (plus \"Other\" with free text). Created as a draft unless `open: true`. One live questionnaire per thread: opening closes the current one. Agent questionnaires carry the AI label. Answers never notify subscribers.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Thread number (e.g. 118) or thread id","example":"118"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFeedbackQuestionnaire"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireWriteResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/questionnaires":{"get":{"summary":"List questionnaires","description":"Questionnaires across threads, most recent answers first, with question, response and held \"Other\" counts. `answeredSince` keeps only those with responses submitted or changed since then.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["draft","live","closed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"Only questionnaires with a response submitted or changed at or after this time","format":"date-time"},"required":false,"name":"answeredSince","in":"query"},{"schema":{"type":"string","description":"Thread number or id"},"required":false,"name":"threadId","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Questionnaires","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireSummaryListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/questionnaires/{id}":{"patch":{"summary":"Edit questionnaire draft","description":"Title, intro and questions of a draft. Live and closed questionnaires are frozen (409): create a new one instead.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Questionnaire id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFeedbackQuestionnaire"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireWriteResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Not a draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/questionnaires/{id}/open":{"post":{"summary":"Open questionnaire","description":"Draft → live. Closes the thread's current live questionnaire in the same step.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Questionnaire id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireAction"}}}},"responses":{"200":{"description":"Live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireWriteResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Closed questionnaires cannot be reopened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/questionnaires/{id}/close":{"post":{"summary":"Close questionnaire","description":"Live → closed. Answers stay; members see the results.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Questionnaire id"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireAction"}}}},"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireWriteResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Not live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/questionnaires/{id}/results":{"get":{"summary":"Get questionnaire results","description":"Complete totals per option, every \"Other\" text with its moderation status and response id, and each member's answers (display identity only, with submitted/updated times). `answeredSince` limits the listed responses to new or changed ones; the totals stay complete.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Questionnaire id"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Only list responses submitted or changed at or after this time. Totals always count every response.","format":"date-time"},"required":false,"name":"answeredSince","in":"query"}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackQuestionnaireResultsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/admin/feedback/questionnaires/{id}/responses/{responseId}":{"post":{"summary":"Review questionnaire free text","description":"Approve or reject the held \"Other\" texts of one response. Picked options count either way.","tags":["Admin"],"security":[{"adminApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Questionnaire id"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Response id"},"required":true,"name":"responseId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewFeedbackQuestionnaireResponse"}}}},"responses":{"200":{"description":"Reviewed","content":{"application/json":{"schema":{"type":"object","properties":{"moderationStatus":{"type":"string","enum":["published","held","rejected"]},"id":{"type":"string"}},"required":["moderationStatus","id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/calc/abv":{"get":{"summary":"ABV calculator","description":"Alcohol by volume, alcohol by weight, attenuation, calories and carbs from original and final gravity.\n\nFree, no authentication. Formula: ABV = 76.08 × (OG − FG) / (1.775 − OG) × FG / 0.794; simple: (OG − FG) × 131.25.\n\nExamples:\n- https://brewforge.sh/api/public/calc/abv?og=1.050&fg=1.010\n- https://brewforge.sh/api/public/calc/abv?og=12.4&fg=2.6&gravityUnit=plato\n- https://brewforge.sh/api/public/calc/abv?og=1.065&fg=1.012&units=imperial&servingSize=16","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Original gravity, in gravityUnit (e.g. 1.050 or 12.4).","example":1.05},"required":true,"name":"og","in":"query"},{"schema":{"type":"number","description":"Final gravity, in gravityUnit (e.g. 1.010 or 2.6).","example":1.01},"required":true,"name":"fg","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":5000,"description":"Serving size for calories and carbs, in servingUnit. Default: 500 ml or 12 fl oz."},"required":false,"name":"servingSize","in":"query"},{"schema":{"type":"string","description":"Unit of the serving size (floz = US fluid ounce). One of: ml, floz. Default: ml (units=metric) or floz (units=imperial).","enum":["ml","floz"]},"required":false,"name":"servingUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"abv","title":"ABV calculator","formula":"ABV = 76.08 × (OG − FG) / (1.775 − OG) × FG / 0.794; simple: (OG − FG) × 131.25","inputs":{"og":{"value":1.05,"unit":"sg"},"fg":{"value":1.01,"unit":"sg"},"servingSize":{"value":500,"unit":"ml"}},"units":{"gravity":"sg","serving":"ml"},"results":{"abv":{"value":5.34,"unit":"%"},"abvSimple":{"value":5.25,"unit":"%"},"abvAlternate":{"value":5.34,"unit":"%"},"abw":{"value":4.19,"unit":"%"},"apparentAttenuation":{"value":80,"unit":"%"},"realAttenuation":{"value":64.9,"unit":"%"},"og":{"sg":1.05,"plato":12.4},"fg":{"sg":1.01,"plato":2.58},"caloriesPerServing":{"value":232,"unit":"kcal"},"carbsPerServing":{"value":21.5,"unit":"g"},"servingSizeMl":{"value":500,"unit":"ml"}},"notes":["abv uses the alternate (Balling) formula, accurate for strong beers too; abvSimple is (OG − FG) × 131.25 for comparison.","abvAlternate is deprecated and equals abv."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/abv","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/ibu":{"get":{"summary":"IBU calculator (Tinseth)","description":"Bitterness (IBU) of hop additions with the Tinseth formula: boil, first wort, mash and whirlpool/hopstand additions with temperature.\n\nFree, no authentication. Formula: Tinseth: IBU = AA/100 × mg/L × 1.65 × 0.000125^(Gb − 1) × (1 − e^(−0.04 t)) / 4.15; whirlpool × temperature factor (mIBU, Arrhenius).\n\nExamples:\n- https://brewforge.sh/api/public/calc/ibu?hops=20:12:60,30:5.5:10&volume=20&og=1.050\n- https://brewforge.sh/api/public/calc/ibu?hops=1:12:60,1:5.5:10&volume=5&og=1.050&units=imperial\n- https://brewforge.sh/api/public/calc/ibu?hops=25:13:60,50:7:20:whirlpool:80&volume=20&og=1.060&hopstandTime=20","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"string","description":"Hop additions, comma-separated amount:alpha:time[:use[:temp]]. amount in weightUnit, alpha in %, time in minutes (boil time left, or whirlpool minutes), use boil (default), fwh, mash or whirlpool, temp = whirlpool temperature in temperatureUnit (default hopstandTemp). E.g. 20:12:60,30:5.5:10,50:7:20:whirlpool:80","example":"20:12:60,30:5.5:10,50:7:20:whirlpool:80"},"required":true,"name":"hops","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":100000,"description":"Batch volume (post-boil wort) in volumeUnit.","example":20},"required":true,"name":"volume","in":"query"},{"schema":{"type":"number","description":"Original gravity in gravityUnit. Used for BU:GU and, when boilGravity is not given, for the average boil gravity: 1 + (OG − 1) × 0.925."},"required":false,"name":"og","in":"query"},{"schema":{"type":"number","description":"Average gravity of the wort during the boil, in gravityUnit (Tinseth's bigness factor). Default: from og."},"required":false,"name":"boilGravity","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":600,"description":"Total boil time in minutes, for first wort and mash hops. Default: 60."},"required":false,"name":"boilTime","in":"query"},{"schema":{"type":"number","description":"Hopstand/whirlpool temperature in temperatureUnit. Default: 80 °C / 176 °F."},"required":false,"name":"hopstandTemp","in":"query"},{"schema":{"type":"number","minimum":0,"maximum":600,"description":"Hopstand minutes after flameout at hopstandTemp: whirlpool additions without their own time use it, and boil and first wort additions keep isomerising during it. 0 turns it off. Default: 20."},"required":false,"name":"hopstandTime","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the hop amounts. One of: g, oz. Default: g (units=metric) or oz (units=imperial).","enum":["g","oz"]},"required":false,"name":"weightUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"ibu","title":"IBU calculator (Tinseth)","formula":"Tinseth: IBU = AA/100 × mg/L × 1.65 × 0.000125^(Gb − 1) × (1 − e^(−0.04 t)) / 4.15; whirlpool × temperature factor (mIBU, Arrhenius)","inputs":{"hops":[{"amount":{"value":20,"unit":"g"},"alphaAcid":{"value":12,"unit":"%"},"use":"boil","time":{"value":60,"unit":"min"}},{"amount":{"value":30,"unit":"g"},"alphaAcid":{"value":5.5,"unit":"%"},"use":"boil","time":{"value":10,"unit":"min"}}],"volume":{"value":20,"unit":"L"},"og":{"value":1.05,"unit":"sg"},"boilGravity":{"sg":1.0463,"plato":11.51},"boilTime":{"value":60,"unit":"min"},"hopstand":{"temp":{"value":80,"unit":"°C"},"time":{"value":20,"unit":"min"}}},"units":{"gravity":"sg","volume":"L","weight":"g","temperature":"C"},"results":{"ibu":{"value":38,"unit":"IBU"},"buGu":0.76,"hops":[{"addition":1,"ibu":{"value":29,"unit":"IBU"},"share":{"value":76.4,"unit":"%"}},{"addition":2,"ibu":{"value":9,"unit":"IBU"},"share":{"value":23.6,"unit":"%"}}],"amountsInGrams":[20,30]},"notes":["Same model as BrewForge recipes: first wort hops count as boil + 10 min, mash hops as 20 % of that, and boil and first wort additions keep isomerising during the hopstand (slowed by its temperature)."],"links":{"docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/beer-color":{"get":{"summary":"Beer color calculator","description":"Beer color (EBC and SRM) from the grain bill, with the Brau!magazin/MMuM formula (needs og) or Morey (needs batchVolume).\n\nFree, no authentication. Formula: Brau!magazin/MMuM (default) or Morey.\n\nExamples:\n- https://brewforge.sh/api/public/calc/beer-color?malts=4.5:3.5,0.5:150&og=1.048\n- https://brewforge.sh/api/public/calc/beer-color?malts=10:2,1:60&og=1.052&units=imperial\n- https://brewforge.sh/api/public/calc/beer-color?malts=4:3.5,1:20&formula=morey&batchVolume=20","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"string","description":"Grain bill: comma-separated amount:color pairs, amount in weightUnit, color in colorUnit (e.g. 4.5:3.5,0.5:150 = 4.5 kg at 3.5 EBC and 0.5 kg at 150 EBC).","example":"4.5:3.5,0.5:150"},"required":true,"name":"malts","in":"query"},{"schema":{"type":"string","enum":["mmum","morey"],"description":"Color formula. Default: mmum (Brau!magazin/MMuM, used for recipes in BrewForge). One of: mmum, morey."},"required":false,"name":"formula","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Original gravity in gravityUnit. Required for formula=mmum.","example":1.048},"required":false,"name":"og","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"number","minimum":0,"maximum":600,"description":"Boil time in minutes (mmum adds 1.5 EBC per hour). Default: 60."},"required":false,"name":"boilTime","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Batch volume in volumeUnit. Required for formula=morey; when given with formula=mmum, the Morey estimate is added for comparison."},"required":false,"name":"batchVolume","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the malt amounts. One of: kg, g, lb, oz. Default: kg (units=metric) or lb (units=imperial).","enum":["kg","g","lb","oz"]},"required":false,"name":"weightUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the malt colors (°Lovibond is treated as ≈ SRM for malts, as in the calculator). One of: ebc, lovibond. Default: ebc (units=metric) or lovibond (units=imperial).","enum":["ebc","lovibond"]},"required":false,"name":"colorUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"beer-color","title":"Beer color calculator","formula":"Brau!magazin/MMuM (default) or Morey","inputs":{"malts":[{"amount":{"value":4.5,"unit":"kg"},"color":{"value":3.5,"unit":"ebc"}},{"amount":{"value":0.5,"unit":"kg"},"color":{"value":150,"unit":"ebc"}}],"formula":"mmum","og":{"value":1.048,"unit":"sg"},"boilTime":{"value":60,"unit":"min"}},"units":{"gravity":"sg","volume":"L","weight":"kg","maltColor":"ebc"},"results":{"ebc":{"value":23.1,"unit":"EBC"},"srm":{"value":11.7,"unit":"SRM"},"hex":"#c25d00","band":{"id":"copper","name":"copper"},"formulaUsed":"Brau!magazin/MMuM: EBC = (Σ (EBCᵢ × mᵢ) / Σ mᵢ) × °P / 10 + 1.5 × boil hours","averageMaltColor":{"value":18.2,"unit":"EBC"},"totalGrainWeightKg":{"value":5,"unit":"kg"}},"notes":["°Lovibond malt colors are treated as ≈ SRM (EBC = °L × 1.97), as in the calculator.","The boil adds 1.5 EBC per hour of boil time."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/beer-color","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/strike-water":{"get":{"summary":"Strike water calculator","description":"Strike water temperature and volume to hit a mash temperature, optionally warming a cold mash tun.\n\nFree, no authentication. Formula: Palmer: Tw = (0.4 / R)(T₂ − T₁) + T₂ (+ tun term: thermal mass / water × (T₂ − T_tun)).\n\nExamples:\n- https://brewforge.sh/api/public/calc/strike-water?mashTemp=67&grainWeight=5&ratio=3\n- https://brewforge.sh/api/public/calc/strike-water?mashTemp=152&grainWeight=11&ratio=1.5&units=imperial\n- https://brewforge.sh/api/public/calc/strike-water?mashTemp=66&grainWeight=6&waterVolume=18&tunWeight=4&tunMaterial=cooler&grainTemp=18","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Target mash temperature in temperatureUnit.","example":67},"required":true,"name":"mashTemp","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":10000,"description":"Grain weight in weightUnit.","example":5},"required":true,"name":"grainWeight","in":"query"},{"schema":{"type":"number","description":"Grain temperature in temperatureUnit. Default: 20 °C / 68 °F."},"required":false,"name":"grainTemp","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":20,"description":"Water-to-grain ratio in ratioUnit. Default: 3 L/kg. Use either ratio or waterVolume."},"required":false,"name":"ratio","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Strike water volume in volumeUnit, instead of ratio."},"required":false,"name":"waterVolume","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":1000,"description":"Weight of a cold (not preheated) mash tun in weightUnit, with tunMaterial."},"required":false,"name":"tunWeight","in":"query"},{"schema":{"type":"string","enum":["stainless","aluminum","cooler"],"description":"Material of the cold mash tun (with tunWeight). One of: stainless, aluminum, cooler."},"required":false,"name":"tunMaterial","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":1000,"description":"Thermal mass of a cold mash tun in volumeUnit of water equivalent, instead of tunWeight and tunMaterial."},"required":false,"name":"tunThermalMass","in":"query"},{"schema":{"type":"number","description":"Temperature of the cold mash tun in temperatureUnit. Default: grainTemp."},"required":false,"name":"tunTemp","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the grain weight. One of: kg, lb. Default: kg (units=metric) or lb (units=imperial).","enum":["kg","lb"]},"required":false,"name":"weightUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the water-to-grain ratio. One of: L/kg, qt/lb. Default: L/kg (units=metric) or qt/lb (units=imperial).","enum":["L/kg","qt/lb"]},"required":false,"name":"ratioUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"strike-water","title":"Strike water calculator","formula":"Palmer: Tw = (0.4 / R)(T₂ − T₁) + T₂ (+ tun term: thermal mass / water × (T₂ − T_tun))","inputs":{"mashTemp":{"value":67,"unit":"°C"},"grainWeight":{"value":5,"unit":"kg"},"grainTemp":{"value":20,"unit":"°C"},"water":{"ratio":{"value":3,"unit":"L/kg"}},"mashTun":"preheated"},"units":{"temperature":"C","volume":"L","weight":"kg","ratio":"L/kg"},"results":{"strikeTemp":{"value":73.3,"unit":"°C"},"strikeWater":{"value":15,"unit":"L"},"ratio":{"value":3,"unit":"L/kg"},"grainCorrection":{"value":6.3,"unit":"°C"},"tunCorrection":{"value":0,"unit":"°C"}},"notes":["grainCorrection and tunCorrection are the degrees above the mash temperature for warming the grain and the tun."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/strike-water","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/step-mash":{"get":{"summary":"Step mash calculator","description":"Strike water for the mash-in, then the boiling water to add (infusion) or thick mash to pull (decoction) for every further rest.\n\nFree, no authentication. Formula: Heat balance with grain specific heat 0.4: infusion V = (T₂ − T₁)(0.4·G + W) / (Tw − T₂); decoction from the same balance with the decoction at 98 °C.\n\nExamples:\n- https://brewforge.sh/api/public/calc/step-mash?grainWeight=5&rests=63:40,72:30,78:10&mashInRatio=3\n- https://brewforge.sh/api/public/calc/step-mash?grainWeight=11&rests=145:40,162:30,169:10&mashInRatio=1.5&units=imperial\n- https://brewforge.sh/api/public/calc/step-mash?grainWeight=5&template=doubleDecoction&mashInRatio=3.5","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","exclusiveMinimum":0,"maximum":10000,"description":"Grain weight in weightUnit.","example":5},"required":true,"name":"grainWeight","in":"query"},{"schema":{"type":"number","description":"Grain temperature in temperatureUnit. Default: 20 °C / 68 °F."},"required":false,"name":"grainTemp","in":"query"},{"schema":{"type":"string","description":"Rests in order, comma-separated temp:minutes[:method]; temperatures in temperatureUnit, method infusion (default), decoction or direct (heating). The first rest is the mash-in. Alternative to template.","example":"63:40,72:30,78:10"},"required":false,"name":"rests","in":"query"},{"schema":{"type":"string","enum":["singleInfusion","hochkurz","proteinRest","doubleDecoction"],"description":"A common schedule instead of rests (°C: singleInfusion 67/78, hochkurz 63/72/78, proteinRest 52/67/78, doubleDecoction 52/64/72). One of: singleInfusion, hochkurz, proteinRest, doubleDecoction."},"required":false,"name":"template","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":20,"description":"Mash-in water-to-grain ratio in ratioUnit. Default: 3 L/kg. Use either mashInRatio or mashInVolume."},"required":false,"name":"mashInRatio","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Mash-in (strike) water in volumeUnit, instead of mashInRatio."},"required":false,"name":"mashInVolume","in":"query"},{"schema":{"type":"number","description":"Temperature of the infusion water in temperatureUnit. Default: boiling (100 °C / 212 °F)."},"required":false,"name":"infusionTemp","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the grain weight. One of: kg, lb. Default: kg (units=metric) or lb (units=imperial).","enum":["kg","lb"]},"required":false,"name":"weightUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the water-to-grain ratio. One of: L/kg, qt/lb. Default: L/kg (units=metric) or qt/lb (units=imperial).","enum":["L/kg","qt/lb"]},"required":false,"name":"ratioUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"step-mash","title":"Step mash calculator","formula":"Heat balance with grain specific heat 0.4: infusion V = (T₂ − T₁)(0.4·G + W) / (Tw − T₂); decoction from the same balance with the decoction at 98 °C","inputs":{"grainWeight":{"value":5,"unit":"kg"},"grainTemp":{"value":20,"unit":"°C"},"rests":[{"temp":{"value":63,"unit":"°C"},"minutes":40,"method":"mashIn"},{"temp":{"value":72,"unit":"°C"},"minutes":30,"method":"infusion"},{"temp":{"value":78,"unit":"°C"},"minutes":10,"method":"infusion"}],"mashIn":{"ratio":{"value":3,"unit":"L/kg"}},"infusionTemp":{"value":100,"unit":"°C"}},"units":{"temperature":"C","volume":"L","weight":"kg","ratio":"L/kg"},"results":{"steps":[{"action":"mashIn","targetTemp":{"value":63,"unit":"°C"},"minutes":40,"startTemp":{"value":20,"unit":"°C"},"waterToAdd":{"value":15,"unit":"L"},"waterTemp":{"value":68.7,"unit":"°C"},"decoctionVolume":null,"totalWater":{"value":15,"unit":"L"},"ratio":{"value":3,"unit":"L/kg"},"warnings":[]},{"action":"infusion","targetTemp":{"value":72,"unit":"°C"},"minutes":30,"startTemp":{"value":63,"unit":"°C"},"waterToAdd":{"value":5.46,"unit":"L"},"waterTemp":{"value":100,"unit":"°C"},"decoctionVolume":null,"totalWater":{"value":20.46,"unit":"L"},"ratio":{"value":4.09,"unit":"L/kg"},"warnings":[]},{"action":"infusion","targetTemp":{"value":78,"unit":"°C"},"minutes":10,"startTemp":{"value":72,"unit":"°C"},"waterToAdd":{"value":6.13,"unit":"L"},"waterTemp":{"value":100,"unit":"°C"},"decoctionVolume":null,"totalWater":{"value":26.59,"unit":"L"},"ratio":{"value":5.32,"unit":"L/kg"},"warnings":[]}],"strikeWater":{"value":15,"unit":"L"},"infusionWater":{"value":11.59,"unit":"L"},"totalWater":{"value":26.59,"unit":"L"},"finalRatio":{"value":5.32,"unit":"L/kg"},"totalRestTime":{"value":80,"unit":"min"},"warnings":[]},"notes":["Decoction volumes are thick mash to pull, boil and return; they add no water.","Assumes a preheated mash tun (no tun heat loss)."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/step-mash","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/dilution":{"get":{"summary":"Dilution calculator","description":"Water to add to bring wort down to a target gravity, and/or the gravity after adding a given amount of water.\n\nFree, no authentication. Formula: Conservation of sugar: V₁ × (SG₁ − 1) = V₂ × (SG₂ − 1).\n\nExamples:\n- https://brewforge.sh/api/public/calc/dilution?gravity=1.060&volume=23&targetGravity=1.050\n- https://brewforge.sh/api/public/calc/dilution?gravity=1.060&volume=6&targetGravity=1.050&units=imperial\n- https://brewforge.sh/api/public/calc/dilution?gravity=14.7&volume=23&water=2&gravityUnit=plato","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Current wort gravity in gravityUnit.","example":1.06},"required":true,"name":"gravity","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Current wort volume in volumeUnit.","example":23},"required":true,"name":"volume","in":"query"},{"schema":{"type":"number","description":"Target gravity in gravityUnit (lower than gravity): returns the water to add.","example":1.05},"required":false,"name":"targetGravity","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Water to add in volumeUnit: returns the resulting gravity and volume."},"required":false,"name":"water","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"dilution","title":"Dilution calculator","formula":"Conservation of sugar: V₁ × (SG₁ − 1) = V₂ × (SG₂ − 1)","inputs":{"gravity":{"value":1.06,"unit":"sg"},"volume":{"value":23,"unit":"L"},"targetGravity":{"value":1.05,"unit":"sg"}},"units":{"gravity":"sg","volume":"L"},"results":{"forTarget":{"waterToAdd":{"value":4.6,"unit":"L"},"finalVolume":{"value":27.6,"unit":"L"},"finalGravity":{"sg":1.05,"plato":12.4}}},"links":{"calculator":"https://brewforge.sh/brewing-calculators/dilution-boil-off","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/boil-off":{"get":{"summary":"Boil-off calculator","description":"Extra boil time and volume to boil off to raise wort to a target gravity, and/or the gravity after boiling longer.\n\nFree, no authentication. Formula: Conservation of sugar: V₁ × (SG₁ − 1) = V₂ × (SG₂ − 1); time = volume to boil off / boil-off rate.\n\nExamples:\n- https://brewforge.sh/api/public/calc/boil-off?gravity=1.040&volume=28&boilOffRate=4&targetGravity=1.050\n- https://brewforge.sh/api/public/calc/boil-off?gravity=1.040&volume=7&boilOffRate=1&targetGravity=1.050&units=imperial\n- https://brewforge.sh/api/public/calc/boil-off?gravity=10&volume=28&boilOffRate=4&boilTime=30&gravityUnit=plato","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Current wort gravity in gravityUnit.","example":1.04},"required":true,"name":"gravity","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Current wort volume in volumeUnit.","example":28},"required":true,"name":"volume","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Boil-off rate in volumeUnit per hour.","example":4},"required":true,"name":"boilOffRate","in":"query"},{"schema":{"type":"number","description":"Target gravity in gravityUnit (higher than gravity): returns the extra boil time.","example":1.05},"required":false,"name":"targetGravity","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":1440,"description":"Extra boil time in minutes: returns the resulting gravity and volume."},"required":false,"name":"boilTime","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"boil-off","title":"Boil-off calculator","formula":"Conservation of sugar: V₁ × (SG₁ − 1) = V₂ × (SG₂ − 1); time = volume to boil off / boil-off rate","inputs":{"gravity":{"value":1.04,"unit":"sg"},"volume":{"value":28,"unit":"L"},"boilOffRate":{"value":4,"unit":"L/h"},"targetGravity":{"value":1.05,"unit":"sg"}},"units":{"gravity":"sg","volume":"L"},"results":{"forTarget":{"additionalBoilTime":{"value":84,"unit":"min"},"volumeToBoilOff":{"value":5.6,"unit":"L"},"finalVolume":{"value":22.4,"unit":"L"},"finalGravity":{"sg":1.05,"plato":12.4}}},"links":{"calculator":"https://brewforge.sh/brewing-calculators/dilution-boil-off","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/hydrometer-correction":{"get":{"summary":"Hydrometer temperature correction","description":"Corrects a hydrometer reading taken at a sample temperature that differs from the hydrometer's calibration temperature.\n\nFree, no authentication. Formula: CG = MG × f(sample °F) / f(calibration °F), f = cubic water-density fit.\n\nExamples:\n- https://brewforge.sh/api/public/calc/hydrometer-correction?gravity=1.050&sampleTemp=25\n- https://brewforge.sh/api/public/calc/hydrometer-correction?gravity=1.050&sampleTemp=77&units=imperial\n- https://brewforge.sh/api/public/calc/hydrometer-correction?gravity=12.4&sampleTemp=30&calibrationTemp=15.56&gravityUnit=plato","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Measured gravity in gravityUnit.","example":1.05},"required":true,"name":"gravity","in":"query"},{"schema":{"type":"number","description":"Sample temperature in temperatureUnit.","example":25},"required":true,"name":"sampleTemp","in":"query"},{"schema":{"type":"number","description":"Calibration temperature of the hydrometer in temperatureUnit. Default: 20 °C / 68 °F.","example":20},"required":false,"name":"calibrationTemp","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"hydrometer-correction","title":"Hydrometer temperature correction","formula":"CG = MG × f(sample °F) / f(calibration °F), f = cubic water-density fit","inputs":{"gravity":{"value":1.05,"unit":"sg"},"sampleTemp":{"value":25,"unit":"°C"},"calibrationTemp":{"value":20,"unit":"°C"}},"units":{"gravity":"sg","temperature":"C"},"results":{"correctedGravity":{"sg":1.0512,"plato":12.68},"correction":{"points":1.17,"plato":0.28},"temperatureDifference":{"value":5,"unit":"°C"}},"notes":[],"links":{"calculator":"https://brewforge.sh/brewing-calculators/hydrometer-temperature-correction","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/refractometer":{"get":{"summary":"Refractometer calculator","description":"Original gravity from a Brix reading, and the alcohol-corrected gravity, attenuation and ABV from a reading taken during or after fermentation.\n\nFree, no authentication. Formula: OG: °P = Brix / WCF; with alcohol: Bonham (in progress) or Terrill linear (finished).\n\nExamples:\n- https://brewforge.sh/api/public/calc/refractometer?originalBrix=12&finalBrix=6\n- https://brewforge.sh/api/public/calc/refractometer?originalBrix=14.5&finalBrix=7.2&stage=finished\n- https://brewforge.sh/api/public/calc/refractometer?originalBrix=12&wcf=1.02","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","exclusiveMinimum":0,"maximum":50,"description":"Refractometer reading of the unfermented wort, in °Brix.","example":12},"required":true,"name":"originalBrix","in":"query"},{"schema":{"type":"number","minimum":0,"maximum":50,"description":"Refractometer reading during or after fermentation, in °Brix (at most originalBrix). Without it only the OG is returned.","example":6},"required":false,"name":"finalBrix","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":1.2,"description":"Wort correction factor of your refractometer. Default: 1.03."},"required":false,"name":"wcf","in":"query"},{"schema":{"type":"string","enum":["in-progress","finished"],"description":"Whether fermentation is still running (Bonham correction) or finished (Terrill linear). Default: in-progress, like the calculator page. One of: in-progress, finished."},"required":false,"name":"stage","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Accepted for consistency; Brix readings and the WCF have no unit system."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"refractometer","title":"Refractometer calculator","formula":"OG: °P = Brix / WCF; with alcohol: Bonham (in progress) or Terrill linear (finished)","inputs":{"originalBrix":{"value":12,"unit":"°Bx"},"finalBrix":{"value":6,"unit":"°Bx"},"wcf":1.03,"stage":"in-progress"},"units":{"reading":"°Bx"},"results":{"og":{"sg":1.0468,"plato":11.65},"method":"Bonham (for readings during fermentation)","gravity":{"sg":1.0094,"plato":2.42},"apparentAttenuation":{"value":79.3,"unit":"%"},"abv":{"value":4.97,"unit":"%"}},"notes":["Readings with alcohol cannot be converted with the WCF alone: use the corrected gravity, not Brix ÷ WCF."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/refractometer","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/priming-sugar":{"get":{"summary":"Priming sugar calculator","description":"Priming sugar for bottle conditioning (corn sugar, table sugar, DME, honey), per batch and per bottle.\n\nFree, no authentication. Formula: sugar = (target CO₂ − residual CO₂ at beer temperature) × liters × sugar factor (g/L per volume).\n\nExamples:\n- https://brewforge.sh/api/public/calc/priming-sugar?volume=20&beerTemp=20&co2=2.4\n- https://brewforge.sh/api/public/calc/priming-sugar?volume=5&beerTemp=68&co2=2.4&units=imperial\n- https://brewforge.sh/api/public/calc/priming-sugar?volume=20&beerTemp=18&style=Hefeweizen&sugar=table_sugar&bottleSize=500","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","exclusiveMinimum":0,"maximum":100000,"description":"Beer volume to bottle, in volumeUnit.","example":20},"required":true,"name":"volume","in":"query"},{"schema":{"type":"number","description":"Highest beer temperature after fermentation, in temperatureUnit (sets the CO₂ already in the beer).","example":20},"required":true,"name":"beerTemp","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":20,"description":"Target carbonation in co2Unit (e.g. 2.4 volumes = 4.7 g/L). Default: the style's typical value, else 2.4 volumes.","example":2.4},"required":false,"name":"co2","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Beer style for the default target CO₂ (case-insensitive). One of: American Lager, Czech Lager, German Lager, Pilsner, American Pale Ale, American IPA, English Pale Ale, English IPA, English Bitter, English Brown Ale, Porter, Stout, Belgian Witbier, Belgian Dubbel, Belgian Tripel, Belgian Quad, Saison, Hefeweizen, Weizenbock, Lambic, Fruit Beer.","example":"American IPA"},"required":false,"name":"style","in":"query"},{"schema":{"type":"string","description":"Unit of the CO₂ target (volumes of CO₂, or grams per liter). Default: volumes. One of: volumes, g/L. Default: volumes.","enum":["volumes","g/L"]},"required":false,"name":"co2Unit","in":"query"},{"schema":{"type":"string","enum":["corn_sugar","table_sugar","dme","honey"],"description":"Priming sugar. Default: corn_sugar. One of: corn_sugar, table_sugar, dme, honey."},"required":false,"name":"sugar","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Bottle size in ml for the per-bottle amount and bottle count. Default: 330 (units=metric) or 355 (units=imperial)."},"required":false,"name":"bottleSize","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the priming sugar results. One of: g, oz. Default: g (units=metric) or oz (units=imperial).","enum":["g","oz"]},"required":false,"name":"weightUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"priming-sugar","title":"Priming sugar calculator","formula":"sugar = (target CO₂ − residual CO₂ at beer temperature) × liters × sugar factor (g/L per volume)","inputs":{"volume":{"value":20,"unit":"L"},"beerTemp":{"value":20,"unit":"°C"},"co2":{"value":2.4,"unit":"volumes"},"sugar":"corn_sugar","bottleSize":{"value":330,"unit":"ml"}},"units":{"volume":"L","temperature":"C","weight":"g","co2":"volumes"},"results":{"sugar":{"value":132.3,"unit":"g"},"sugarPerBottle":{"value":2.18,"unit":"g"},"bottleCount":60,"residualCo2":{"value":0.86,"unit":"volumes"},"co2ToAdd":{"value":1.54,"unit":"volumes"},"allSugars":{"table_sugar":{"value":117.5,"unit":"g"},"corn_sugar":{"value":132.3,"unit":"g"},"dme":{"value":164,"unit":"g"},"honey":{"value":150.8,"unit":"g"}}},"notes":["The total sugar is rounded to 0.1 g (before any conversion to oz), like on the calculator page."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/priming-sugar","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/force-carbonation":{"get":{"summary":"Force carbonation calculator","description":"Regulator pressure to force-carbonate a keg to a target CO₂ level at the serving temperature.\n\nFree, no authentication. Formula: Carbonation table fit (°F): PSI = −16.6999 − 0.0101059·T + 0.00116512·T² + 0.173354·T·V + 4.24267·V − 0.0684226·V².\n\nExamples:\n- https://brewforge.sh/api/public/calc/force-carbonation?temperature=4&co2=2.5\n- https://brewforge.sh/api/public/calc/force-carbonation?temperature=38&co2=2.5&units=imperial\n- https://brewforge.sh/api/public/calc/force-carbonation?temperature=3&co2=5&co2Unit=g/L","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Beer temperature in the keg (serving temperature), in temperatureUnit.","example":4},"required":true,"name":"temperature","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":20,"description":"Target carbonation in co2Unit (e.g. 2.4 volumes = 4.7 g/L). Default: the style's typical value, else 2.4 volumes.","example":2.4},"required":false,"name":"co2","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Beer style for the default target CO₂ (case-insensitive). One of: American Lager, Czech Lager, German Lager, Pilsner, American Pale Ale, American IPA, English Pale Ale, English IPA, English Bitter, English Brown Ale, Porter, Stout, Belgian Witbier, Belgian Dubbel, Belgian Tripel, Belgian Quad, Saison, Hefeweizen, Weizenbock, Lambic, Fruit Beer.","example":"American IPA"},"required":false,"name":"style","in":"query"},{"schema":{"type":"string","description":"Unit of the CO₂ target (volumes of CO₂, or grams per liter). Default: volumes. One of: volumes, g/L. Default: volumes.","enum":["volumes","g/L"]},"required":false,"name":"co2Unit","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"force-carbonation","title":"Force carbonation calculator","formula":"Carbonation table fit (°F): PSI = −16.6999 − 0.0101059·T + 0.00116512·T² + 0.173354·T·V + 4.24267·V − 0.0684226·V²","inputs":{"temperature":{"value":4,"unit":"°C"},"co2":{"value":2.5,"unit":"volumes"}},"units":{"temperature":"C","co2":"volumes"},"results":{"pressure":{"psi":11.9,"bar":0.82}},"notes":["Gauge pressure (above atmosphere). 0 psi means the target is reached without extra pressure at this temperature."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/priming-sugar","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/spunding":{"get":{"summary":"Spunding calculator","description":"Spunding valve pressure for a CO₂ target at fermentation temperature, and the gravity at which to close the fermenter so fermentation carbonates the beer.\n\nFree, no authentication. Formula: Pressure from the carbonation table fit; trigger gravity = FG + CO₂ still needed / 0.54 volumes per gravity point + safety margin.\n\nExamples:\n- https://brewforge.sh/api/public/calc/spunding?temperature=20&fg=1.010&co2=2.4&gravity=1.020&og=1.050&days=3\n- https://brewforge.sh/api/public/calc/spunding?temperature=68&fg=1.010&co2=2.4&units=imperial\n- https://brewforge.sh/api/public/calc/spunding?temperature=12&fg=2.5&gravityUnit=plato&style=Pilsner","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Fermentation temperature in temperatureUnit.","example":20},"required":true,"name":"temperature","in":"query"},{"schema":{"type":"number","description":"Expected final gravity in gravityUnit.","example":1.01},"required":true,"name":"fg","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":20,"description":"Target carbonation in co2Unit. Default: the style's typical value, else 2.4 volumes.","example":2.4},"required":false,"name":"co2","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Beer style for the default target CO₂ (case-insensitive). One of: American Lager, Czech Lager, German Lager, Pilsner, American Pale Ale, American IPA, English Pale Ale, English IPA, English Bitter, English Brown Ale, Porter, Stout, Belgian Witbier, Belgian Dubbel, Belgian Tripel, Belgian Quad, Saison, Hefeweizen, Weizenbock, Lambic, Fruit Beer."},"required":false,"name":"style","in":"query"},{"schema":{"type":"number","description":"Current gravity in gravityUnit: returns the gravity points to go and whether the trigger is passed."},"required":false,"name":"gravity","in":"query"},{"schema":{"type":"number","description":"Original gravity in gravityUnit: with days, returns a rough time until the trigger gravity."},"required":false,"name":"og","in":"query"},{"schema":{"type":"number","minimum":0,"maximum":365,"description":"Days since pitching (with og and gravity)."},"required":false,"name":"days","in":"query"},{"schema":{"type":"number","minimum":0,"maximum":50,"description":"Gravity left on top of what carbonation needs, in gravity points (0.001 SG) for gravityUnit=sg or °P for gravityUnit=plato. Default: 4 points (1 °P)."},"required":false,"name":"safetyMargin","in":"query"},{"schema":{"type":"string","description":"Unit of the CO₂ target (volumes of CO₂, or grams per liter). Default: volumes. One of: volumes, g/L. Default: volumes.","enum":["volumes","g/L"]},"required":false,"name":"co2Unit","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"spunding","title":"Spunding calculator","formula":"Pressure from the carbonation table fit; trigger gravity = FG + CO₂ still needed / 0.54 volumes per gravity point + safety margin","inputs":{"temperature":{"value":20,"unit":"°C"},"fg":{"value":1.01,"unit":"sg"},"co2":{"value":2.4,"unit":"volumes"},"gravity":{"value":1.02,"unit":"sg"},"og":{"value":1.05,"unit":"sg"},"days":{"value":3,"unit":"days"},"safetyMargin":{"value":4,"unit":"points"}},"units":{"gravity":"sg","temperature":"C","co2":"volumes"},"results":{"valvePressure":{"psi":26.1,"bar":1.8},"triggerGravity":{"sg":1.0168,"plato":4.31},"co2Breakdown":{"residualAtTemperature":{"value":0.86,"unit":"volumes"},"fromFermentation":{"value":3.7,"unit":"volumes"},"gravityPointsForCo2":2.8,"safetyMarginPoints":4},"current":{"pointsToGo":3.2,"pastTrigger":false,"hoursToTrigger":8}},"notes":["Set the spunding valve to valvePressure and close the fermenter when the gravity reaches triggerGravity."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/spunding","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/yeast-pitch-rate":{"get":{"summary":"Yeast pitch rate calculator","description":"Cells needed for a batch, viable cells in your packages, and the starter (or extra dry yeast packets) to make up the difference.\n\nFree, no authentication. Formula: cells = pitch rate (M/mL/°P) × mL × °P; liquid viability 97 % − ~21 %/month; starters: Braukaiser (stir plate) or White (shaken).\n\nExamples:\n- https://brewforge.sh/api/public/calc/yeast-pitch-rate?og=1.050&volume=20&productionDate=2026-09-01&date=2026-10-15\n- https://brewforge.sh/api/public/calc/yeast-pitch-rate?og=1.050&volume=5&lager=true&productionDate=2026-09-01&date=2026-10-15&units=imperial\n- https://brewforge.sh/api/public/calc/yeast-pitch-rate?og=1.060&volume=20&form=dry&packages=1&productionDate=2027-06-30&date=2026-10-15\n- https://brewforge.sh/api/public/calc/yeast-pitch-rate?og=1.072&volume=20&lager=true&pitchRate=1.75&productionDate=2026-09-01&date=2026-10-15","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Original gravity in gravityUnit.","example":1.05},"required":true,"name":"og","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":100000,"description":"Batch volume in volumeUnit.","example":20},"required":true,"name":"volume","in":"query"},{"schema":{"type":"boolean","description":"Lager pitch rate (1.5 M cells/mL/°P, 2.0 above 1.060) instead of ale (0.75, 1.0 above 1.065, 1.25 above 1.085). Default: false."},"required":false,"name":"lager","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":5,"description":"Pitch rate in million cells/mL/°P, instead of the recommendation from og and lager (e.g. 0.75 ale, 1.5 lager). Max 5."},"required":false,"name":"pitchRate","in":"query"},{"schema":{"type":"string","enum":["liquid","dry"],"description":"Yeast form. Default: liquid. One of: liquid, dry."},"required":false,"name":"form","in":"query"},{"schema":{"type":"string","enum":["whiteLabsVial","wyeastSmackPack","imperialPouch","dryPacket11g"],"description":"Package type: 100 B cells (whiteLabsVial, wyeastSmackPack), 200 B (imperialPouch, dryPacket11g). Default: whiteLabsVial (liquid) or dryPacket11g (dry). Ignored with cells. One of: whiteLabsVial, wyeastSmackPack, imperialPouch, dryPacket11g."},"required":false,"name":"package","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":10000,"description":"Cells per package in billions, instead of package."},"required":false,"name":"cells","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Packages you have. Default: 1."},"required":false,"name":"packages","in":"query"},{"schema":{"type":"string","description":"Liquid yeast: production date. Dry yeast: best-before date. YYYY-MM-DD. Default: date (fresh liquid yeast) or one year after date (dry).","example":"2026-10-01","format":"date"},"required":false,"name":"productionDate","in":"query"},{"schema":{"type":"string","description":"Pitch date, YYYY-MM-DD. Default: today (UTC).","example":"2026-10-15","format":"date"},"required":false,"name":"date","in":"query"},{"schema":{"type":"number","minimum":0,"maximum":99,"description":"Viability loss per month in percent (liquid: from production; dry: after best-before). Default: 21 (liquid) or 1.5 (dry)."},"required":false,"name":"monthlyLoss","in":"query"},{"schema":{"type":"boolean","description":"Starter on a stir plate (Braukaiser model) instead of shaken (White model). Default: true."},"required":false,"name":"stirPlate","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":3,"description":"Starter steps (1–3). Default: 1."},"required":false,"name":"starterSteps","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":20,"description":"Largest starter step in liters (flask size). Default: 2."},"required":false,"name":"flaskSize","in":"query"},{"schema":{"type":"string","description":"Unit of every gravity parameter (SG like 1.050, or °Plato like 12.4). One of: sg, plato. Default: sg.","enum":["sg","plato"]},"required":false,"name":"gravityUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every volume parameter and result (gal = US gallon). One of: L, gal. Default: L (units=metric) or gal (units=imperial).","enum":["L","gal"]},"required":false,"name":"volumeUnit","in":"query"},{"schema":{"type":"string","description":"Unit of the starter DME amount. One of: g, oz. Default: g (units=metric) or oz (units=imperial).","enum":["g","oz"]},"required":false,"name":"weightUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"yeast-pitch-rate","title":"Yeast pitch rate calculator","formula":"cells = pitch rate (M/mL/°P) × mL × °P; liquid viability 97 % − ~21 %/month; starters: Braukaiser (stir plate) or White (shaken)","inputs":{"og":{"value":1.05,"unit":"sg"},"volume":{"value":20,"unit":"L"},"lager":false,"form":"liquid","package":"whiteLabsVial","cellsPerPackage":{"value":100,"unit":"billion cells"},"packages":1,"productionDate":"2026-09-01","date":"2026-10-15","monthlyLoss":{"value":21,"unit":"%"},"stirPlate":true,"starterSteps":1,"flaskSize":{"value":2,"unit":"L"}},"units":{"gravity":"sg","volume":"L","weight":"g"},"results":{"og":{"sg":1.05,"plato":12.4},"pitchRate":{"value":0.75,"unit":"million cells/mL/°P"},"requiredCells":{"value":186,"unit":"billion cells"},"viability":{"value":69,"unit":"%"},"viableCellsPerPackage":{"value":69,"unit":"billion cells"},"viableCells":{"value":69,"unit":"billion cells"},"packagesNeededWithoutStarter":3,"starterRecommended":true,"starter":{"volume":{"value":0.84,"unit":"L"},"dme":{"value":84,"unit":"g"},"reachesTarget":true,"minimumSteps":1,"steps":[{"step":1,"volume":{"value":0.84,"unit":"L"},"dme":{"value":84,"unit":"g"},"startingCells":{"value":69,"unit":"billion cells"},"endingCells":{"value":186,"unit":"billion cells"},"growthFactor":2.7}]},"extraPackages":0,"pitchPackages":1,"finalCells":{"value":186,"unit":"billion cells"},"achievedPitchRate":{"value":0.75,"unit":"million cells/mL/°P"}},"notes":["Starter volumes are in liters and DME is dry malt extract for the starter wort."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/yeast-pitch-rate","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/hop-freshness":{"get":{"summary":"Hop freshness calculator","description":"Alpha acid left in stored hops (Hop Storage Index model), the amount to use instead, and the shelf life to 75 % retention.\n\nFree, no authentication. Formula: Garetz/HSI: retention = (1 − HSI)^(days / 180 × temperature factor × packaging factor).\n\nExamples:\n- https://brewforge.sh/api/public/calc/hop-freshness?alphaAcid=12.5&harvestDate=2025-09-15&date=2026-03-15&variety=Citra&amount=30\n- https://brewforge.sh/api/public/calc/hop-freshness?alphaAcid=12.5&harvestDate=2025-09-15&date=2026-03-15&variety=Citra&amount=1&units=imperial\n- https://brewforge.sh/api/public/calc/hop-freshness?alphaAcid=6&harvestDate=2025-09-01&storage=room&packaging=loose&hsi=50","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","exclusiveMinimum":0,"maximum":30,"description":"Alpha acid on the package, in percent.","example":12.5},"required":true,"name":"alphaAcid","in":"query"},{"schema":{"type":"string","description":"Harvest or packaging date, YYYY-MM-DD.","example":"2026-03-01","format":"date"},"required":true,"name":"harvestDate","in":"query"},{"schema":{"type":"string","description":"Reference date, YYYY-MM-DD. Default: today (UTC).","example":"2026-10-01","format":"date"},"required":false,"name":"date","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":60,"description":"Hop variety, used to look up its Hop Storage Index (e.g. Citra). Unknown varieties use HSI 40. Ignored when hsi is given.","example":"Citra"},"required":false,"name":"variety","in":"query"},{"schema":{"type":"number","minimum":0,"maximum":99.9,"description":"Hop Storage Index in percent (alpha acid lost in 6 months at 20 °C). Default: by variety, else 40."},"required":false,"name":"hsi","in":"query"},{"schema":{"type":"string","enum":["frozen","refrigerated","cool","room","warm"],"description":"Storage temperature. Default: refrigerated. One of: frozen, refrigerated, cool, room, warm."},"required":false,"name":"storage","in":"query"},{"schema":{"type":"string","enum":["vacuum_sealed","sealed_bag","opened_resealed","loose"],"description":"Packaging. Default: vacuum_sealed. One of: vacuum_sealed, sealed_bag, opened_resealed, loose."},"required":false,"name":"packaging","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"description":"Hop amount from the recipe, in weightUnit: returns the amount of these hops that gives the same bitterness."},"required":false,"name":"amount","in":"query"},{"schema":{"type":"string","description":"Unit of the hop amounts. One of: g, oz. Default: g (units=metric) or oz (units=imperial).","enum":["g","oz"]},"required":false,"name":"weightUnit","in":"query"},{"schema":{"type":"string","description":"Unit of every temperature parameter and result. One of: C, F. Default: C (units=metric) or F (units=imperial).","enum":["C","F"]},"required":false,"name":"temperatureUnit","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Default unit system for every value without an explicit unit parameter (metric: °C, L, kg, g; imperial: °F, US gal, lb, oz). Default: metric. One of: metric, imperial."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"hop-freshness","title":"Hop freshness calculator","formula":"Garetz/HSI: retention = (1 − HSI)^(days / 180 × temperature factor × packaging factor)","inputs":{"alphaAcid":{"value":12.5,"unit":"%"},"harvestDate":"2025-09-15","date":"2026-03-15","variety":"Citra","hsi":{"value":38,"unit":"%"},"storage":{"id":"refrigerated","temperatureRange":{"min":{"value":0,"unit":"°C"},"max":{"value":4,"unit":"°C"}}},"packaging":"vacuum_sealed","amount":{"value":30,"unit":"g"}},"units":{"weight":"g","temperature":"C"},"results":{"currentAlphaAcid":{"value":11.26,"unit":"%"},"retention":{"value":90.1,"unit":"%"},"loss":{"value":9.9,"unit":"%"},"age":{"value":5.9,"unit":"months"},"rating":"excellent","lossPerMonth":{"value":1.74,"unit":"%"},"amountIncrease":{"value":11,"unit":"%"},"adjustedAmount":{"value":33.3,"unit":"g"},"shelfLife":{"until75PercentRetention":{"value":10.3,"unit":"months"},"date":"2027-01-22"},"recommendation":"Hops are very fresh. Use for any purpose including aroma and dry hopping."},"notes":["Ratings: excellent ≥ 90 %, good ≥ 75 %, fair ≥ 50 %, poor ≥ 25 % retention. shelfLife is null when retention is already at or below 75 %."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/hop-freshness","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/public/calc/unit-converter":{"get":{"summary":"Brewing unit converter","description":"Converts gravity (SG, °Plato, Brix), color (SRM, EBC, °L), temperature, volume, weight and pressure.\n\nFree, no authentication. Formula: Unit conversion via one base unit per category (°P, SRM, °C, L, g, psi); Brix to °P with WCF 1.03.\n\nExamples:\n- https://brewforge.sh/api/public/calc/unit-converter?value=1.050&from=sg\n- https://brewforge.sh/api/public/calc/unit-converter?value=5&from=gal&to=liters\n- https://brewforge.sh/api/public/calc/unit-converter?value=152&from=F&to=C","tags":["Calculators"],"security":[],"parameters":[{"schema":{"type":"number","description":"Value to convert, in the from unit.","example":1.05},"required":true,"name":"value","in":"query"},{"schema":{"type":"string","enum":["sg","plato","brix","srm","ebc","lovibond","celsius","fahrenheit","kelvin","liters","usGallons","imperialGallons","usQuarts","kilograms","pounds","grams","ounces","bar","psi","kilopascals"],"description":"Unit of the value. One of: sg, plato, brix, srm, ebc, lovibond, celsius, fahrenheit, kelvin, liters, usGallons, imperialGallons, usQuarts, kilograms, pounds, grams, ounces, bar, psi, kilopascals."},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","enum":["sg","plato","brix","srm","ebc","lovibond","celsius","fahrenheit","kelvin","liters","usGallons","imperialGallons","usQuarts","kilograms","pounds","grams","ounces","bar","psi","kilopascals"],"description":"Target unit (same category). Default: every other unit of the category. One of: sg, plato, brix, srm, ebc, lovibond, celsius, fahrenheit, kelvin, liters, usGallons, imperialGallons, usQuarts, kilograms, pounds, grams, ounces, bar, psi, kilopascals."},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","enum":["metric","imperial"],"description":"Accepted for consistency; from and to set the units here."},"required":false,"name":"units","in":"query"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorResponse"},"example":{"calculator":"unit-converter","title":"Brewing unit converter","formula":"Unit conversion via one base unit per category (°P, SRM, °C, L, g, psi); Brix to °P with WCF 1.03","inputs":{"value":{"value":1.05,"unit":"sg","symbol":"SG"},"category":"gravity"},"units":{"from":"sg"},"results":{"conversions":[{"unit":"plato","symbol":"°P","value":12.4,"rounded":12.4},{"unit":"brix","symbol":"Brix","value":12.772,"rounded":12.8}]},"notes":["Brix here means a refractometer reading of unfermented wort (°P = Brix / 1.03)."],"links":{"calculator":"https://brewforge.sh/brewing-calculators/unit-converter","docs":"https://docs.brewforge.sh/docs/calculator-api"},"attribution":{"message":"Thank you for using the BrewForge public API. Please attribute this calculation to BrewForge (https://brewforge.sh).","source":"BrewForge","url":"https://brewforge.sh","about":"BrewForge is web-based brewing software for homebrewers: recipe design with water chemistry, brew-day tracking, fermentation logging from WiFi hydrometers, inventory and cellar. Free plan available; free calculators at https://brewforge.sh/brewing-calculators."}}}}},"400":{"description":"Invalid or missing parameters (the response lists the expected ones)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCalculatorError"}}}},"429":{"description":"Rate limited: more than 25 requests in 10 minutes from one IP address"}}}},"/api/v1/actions/get_started":{"post":{"operationId":"get_started","tags":["Actions: Getting started"],"summary":"Get started","description":"Call this first. Returns the BrewForge account (name, plan), the user's display units, which plan features are enabled, what this token may do, how many brews exist per status, the toolsets with their tools, and the conventions all tools follow.\n\nAny valid token.","x-brewforge-action":{"toolset":"core","access":"read","required_scope":null,"idempotent":true},"security":[{"bearerAuth":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"name":{"type":"string"},"handle":{"type":"string","description":"Public community handle (username)."},"plan":{"type":"string"}},"required":["name","plan"]},"display_units":{"type":"object","additionalProperties":{"type":"string"}},"features":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"}},"not_enabled":{"type":"array","items":{"type":"string"}}},"required":["enabled","not_enabled"]},"access":{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string"}},"can_write":{"type":"boolean"}},"required":["scopes","can_write"]},"brews":{"type":"object","properties":{"total":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["total","by_status"]},"toolsets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"available":{"type":"boolean","description":"false: none of this toolset's tools can be called on this connection; see not_available_because."},"tools":{"type":"array","items":{"type":"string"},"description":"Tools you can call on this connection."},"not_available_because":{"type":"string","description":"Why tools of this toolset are missing, and how the user can change it."}},"required":["name","description","available","tools"]}},"conventions":{"type":"array","items":{"type":"string"}}},"required":["account","display_units","features","access","brews","toolsets","conventions"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/find_brews":{"post":{"operationId":"find_brews","tags":["Actions: Brewing"],"summary":"Find brews","description":"List the user's brews (every batch and recipe idea), newest activity first. Filter by name, batch number, status or tag. Returns compact rows (id, name, batch number, status, style, dates); call get_brew with an id for details. Brews can be referenced by id, batch number or exact name in other tools, so use this when you need to search, not to look up one brew you already know.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Text the brew name contains, or a batch number (e.g. \"pale ale\", \"12\", \"#12\")."},"status":{"type":"array","items":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"description":"Only brews in these statuses, e.g. [\"fermenting\", \"conditioning\"]. Lifecycle: idea → planned → brewing → fermenting → conditioning → completed → archived."},"tag":{"type":"string","description":"Only brews with this tag (exact, e.g. \"competition\")."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 20)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"style":{"type":"string"},"brew_date":{"type":"string","description":"YYYY-MM-DD, set once brewed."},"planned_date":{"type":"string","description":"YYYY-MM-DD, planned brew day."},"tags":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean"}},"required":["id","name","status"]}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_brew":{"post":{"operationId":"get_brew","tags":["Actions: Brewing"],"summary":"Get a brew","description":"One brew with its status, dates, style and planned stats (OG/FG as SG, ABV %, IBU, color EBC), out-of-style warnings, plus actual stats once measured. Heavy sections only on request with include: \"recipe\" (ingredients with entry ids for update_recipe, mash and fermentation steps; L, g, °C), \"measured\" (brew-day measurements), \"readings\" (newest fermentation readings), \"notes\" (newest notes), \"versions\" (version history: every version and batch of this recipe), \"cost\" (ingredient cost from inventory prices, in the user's currency). Reference the brew by id, batch number or exact name.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"include":{"type":"array","items":{"type":"string","enum":["recipe","measured","readings","notes","versions","cost"]},"description":"Extra sections to include, e.g. [\"recipe\", \"versions\"]. Default: none (summary only)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"planned":{"type":"object","properties":{"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number"},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"abv_pct":{"type":"number"},"ibu":{"type":"number"},"color_ebc":{"type":"number"}},"description":"Gravities as SG, ABV in %, color in EBC."},"actual":{"type":"object","properties":{"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number"},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"abv_pct":{"type":"number"},"ibu":{"type":"number"},"color_ebc":{"type":"number"}},"description":"Gravities as SG, ABV in %, color in EBC."},"readings":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","description":"ISO 8601 timestamp."},"gravity_sg":{"type":"number"},"gravity_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"temp_c":{"type":"number"},"ph":{"type":"number"},"pressure_psi":{"type":"number"},"comment":{"type":"string"}},"required":["at"]}}},"required":["id","name","status"],"additionalProperties":true}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/find_recipes":{"post":{"operationId":"find_recipes","tags":["Actions: Brewing"],"summary":"Browse the recipe book","description":"The recipe book: one row per recipe (all its versions and batches grouped), newest activity first, with style, version count, times brewed (batches), last brew date and BJCP score. query matches text in the recipe name, its style and the style's BJCP category, so \"lager\" also finds a German Pils filed under a lager category, but only by text: for a family the brewer defines (e.g. \"house lagers\"), use tag. sort: recent (default), last_brewed, times_brewed or name. Use it to answer \"what have I brewed\" or to pick a recipe to brew again (copy_brew). For one recipe's version history call get_brew with include [\"versions\"]; for individual batches use find_brews.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Text the recipe name, style or style category contains, e.g. \"ipa\" or \"lager\". Several alternatives separated by commas match any of them, e.g. \"pale ale, ipa\"."},"tag":{"type":"string","description":"Only recipes whose newest version has this tag, e.g. \"competition\"."},"sort":{"type":"string","enum":["recent","last_brewed","times_brewed","name"],"description":"\"recent\" (default: latest change first), \"last_brewed\" (most recently brewed first, never-brewed last), \"times_brewed\" (most batches first) or \"name\"."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 20)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"recipe_id":{"type":"string","description":"Recipe id: copy_brew, get_brew and other tools accept it."},"name":{"type":"string"},"latest_brew_id":{"type":"string","description":"The newest version's brew; use it with get_brew include [\"recipe\"]."},"latest_version":{"type":"string","description":"e.g. \"v3\"."},"style":{"type":"string"},"versions":{"type":"integer"},"batches":{"type":"integer","description":"How many times it was brewed."},"last_brewed":{"type":"string","description":"YYYY-MM-DD"},"bjcp_avg_score":{"type":"number","description":"Average BJCP score of the newest scored version (0-50)."},"tags":{"type":"array","items":{"type":"string"}}},"required":["recipe_id","name","latest_brew_id","versions","batches"]}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/create_brew":{"post":{"operationId":"create_brew","tags":["Actions: Brewing"],"summary":"Create a recipe / brew","description":"Create a new brew from scratch: a recipe idea, or a planned batch when you pass planned_date. Everything but the name is optional; the brewer's default equipment, mash and fermentation profiles fill what you leave out. Reference ingredients, style and profiles by name; unknown names fail with candidates and nothing is created. Returns the new brew with its planned stats (OG/FG as SG, ABV %, IBU, color EBC) and the recipe with entry ids, plus the equipment profile and efficiency it was calculated with. To hit an OG or IBU send target_og (gravity_unit \"plato\" for °P) / target_ibu: malt and bittering hops are scaled like the recipe editor's targets, no trial and error. Change it afterwards with update_recipe (ingredients, process) or update_brew (name, dates, tags). To start from an existing recipe use copy_brew instead; to import BeerXML/MMuM use import_recipe.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name of the beer, e.g. \"West Coast IPA\"."},"planned_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Planned brew day; makes the brew \"planned\" and gives it a batch number (YYYY-MM-DD, e.g. \"2026-11-21\")."},"ready_by_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the beer must be ready (drinkable) by (YYYY-MM-DD, e.g. \"2026-12-24\")."},"ready_by_note":{"type":"string","maxLength":200,"description":"What it is ready for, e.g. \"Christmas party\"."},"description":{"type":"string","maxLength":5000,"description":"Free-text description or notes."},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"description":"Tags, e.g. [\"hoppy\", \"competition\"]."},"brew_type":{"type":"string","enum":["all_grain","partial_mash","extract"],"description":"\"all_grain\" (default), \"partial_mash\" or \"extract\"."},"style":{"type":"string","description":"Beer style: a BJCP 2021 style name or code (e.g. \"American IPA\", \"Hazy IPA\", \"German Pils\" or \"21A\"), or the name of one of the brewer's own styles. Unknown names fail with similar styles. Send \"none\" to clear it."},"equipment_profile":{"type":"string","description":"Name or id of one of the brewer's equipment profiles (e.g. \"Braumeister 20L\"). Sets batch volume, boil time and efficiency from the profile unless you also send them."},"mash_profile":{"type":"string","description":"Name or id of one of the brewer's mash profiles (e.g. \"Single infusion 67°C\"). Replaces the mash steps."},"fermentation_profile":{"type":"string","description":"Name or id of one of the brewer's fermentation profiles (e.g. \"Ale 19°C\"). Replaces the fermentation stages."},"water_source_profile":{"type":"string","description":"Name or id of one of the brewer's water profiles (e.g. \"Munich tap water\"). Used as the recipe's source water."},"water_target_profile":{"type":"string","description":"Name or id of one of the brewer's water profiles (e.g. \"Balanced\"). Used as the recipe's target water."},"batch_volume_l":{"type":"number","exclusiveMinimum":0,"maximum":10000,"description":"Batch volume in liters (into the fermenter), e.g. 20."},"boil_time_min":{"type":"number","minimum":0,"maximum":600,"description":"Boil time in minutes, e.g. 60."},"efficiency_pct":{"type":"number","minimum":1,"maximum":100,"description":"Brewhouse efficiency in %, e.g. 72."},"mash_steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Step name, e.g. \"Saccharification rest\" (default \"Rest 1\", \"Rest 2\", ...)."},"type":{"type":"string","enum":["infusion","temperature","decoction"],"description":"\"infusion\" (default for the first step), \"temperature\" (heated, default for later steps) or \"decoction\"."},"temp":{"type":"number","description":"Rest temperature in temp_unit (default °C), e.g. 67."},"duration_min":{"type":"number","minimum":0,"description":"Rest time in minutes, e.g. 60."}},"required":["temp","duration_min"],"additionalProperties":false},"description":"The full list of mash rests in order; replaces the current steps."},"fermentation_stages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Stage name, e.g. \"Primary\" (default from type)."},"type":{"type":"string","enum":["primary","secondary","tertiary","cold_crash","conditioning","carbonation"],"description":"\"primary\" (default for the first stage), \"secondary\", \"tertiary\", \"cold_crash\", \"conditioning\" or \"carbonation\"."},"temp":{"type":"number","description":"Temperature in temp_unit (default °C), e.g. 19."},"duration_days":{"type":"number","minimum":0,"description":"Duration in days, e.g. 10."}},"required":["temp","duration_days"],"additionalProperties":false},"description":"The full list of fermentation stages in order; replaces the current stages."},"temp_unit":{"type":"string","enum":["c","f"],"description":"Unit of the temperatures you send: \"c\" (°C, default) or \"f\" (°F)."},"fg_override_sg":{"anyOf":[{"type":"number","minimum":0.98,"maximum":1.1},{"type":"null"}],"description":"Planned FG to use instead of the one calculated from yeast attenuation, as SG (e.g. 1.012). null removes the override."},"target_og":{"type":"number","description":"OG to hit, as the brew page shows it, in gravity_unit (SG by default, e.g. 1.052; or °P with gravity_unit \"plato\", e.g. 12.9). Scales the malt amounts and keeps their shares, like the recipe editor's target OG (percentage mode stays on)."},"target_ibu":{"type":"number","minimum":0,"maximum":200,"description":"IBU to hit, as the brew page shows it, e.g. 35. Scales every IBU-giving hop addition (all boil times incl. late ones, first wort, whirlpool; not dry hops) keeping each one's share of the IBU, like the recipe editor's IBU target (stays on). Applied after ingredient changes in the same call."},"gravity_unit":{"type":"string","enum":["sg","plato"],"description":"Unit of the gravity values you send: \"sg\" (specific gravity, e.g. 1.012; default) or \"plato\" (°P, e.g. 3.1)."},"fermentables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The fermentable (malt, sugar, extract) from the brewer's ingredient library: its exact name (e.g. \"Pilsner Malt\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount_g":{"type":"number","exclusiveMinimum":0,"description":"Amount in grams, e.g. 4500 for 4.5 kg."},"add_at":{"type":"string","enum":["mash","lauter","boil","fermentation"],"description":"When it goes in: \"mash\" (default), \"lauter\", \"boil\" or \"fermentation\"."}},"required":["name","amount_g"],"additionalProperties":false},"description":"Fermentables, e.g. [{\"name\": \"Pale Ale Malt\", \"amount_g\": 5000}]."},"hops":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The hop from the brewer's ingredient library: its exact name (e.g. \"Citra\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount_g":{"type":"number","exclusiveMinimum":0,"description":"Amount in grams, e.g. 25."},"use":{"type":"string","enum":["boil","first_wort","mash","whirlpool","dry_hop"],"description":"\"boil\" (default), \"first_wort\", \"mash\", \"whirlpool\" (hopstand after flameout) or \"dry_hop\"."},"time_min":{"type":"number","minimum":0,"description":"boil/first_wort/mash: minutes before the end of the boil (e.g. 60 = bittering, 10 = flavor; default 60). whirlpool: minute after flameout it goes in (default 0)."},"day":{"type":"number","minimum":0,"description":"dry_hop only: fermentation day it goes in, e.g. 5."},"duration_days":{"type":"number","minimum":0,"description":"dry_hop only: contact days before it is removed, e.g. 3."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Alpha acid in % if it differs from the library value, e.g. 12.5."},"form":{"type":"string","enum":["pellet","whole","cryo","extract"],"description":"\"pellet\" (default), \"whole\", \"cryo\" or \"extract\"."}},"required":["name","amount_g"],"additionalProperties":false},"description":"Hop additions, e.g. [{\"name\": \"Citra\", \"amount_g\": 20, \"use\": \"boil\", \"time_min\": 60}, {\"name\": \"Citra\", \"amount_g\": 50, \"use\": \"dry_hop\", \"day\": 5, \"duration_days\": 3}]."},"yeasts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The yeast from the brewer's ingredient library: its exact name (e.g. \"SafAle US-05\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount in unit (default 1)."},"unit":{"type":"string","enum":["pkg","g","ml","cells"],"description":"\"pkg\" (packs, default), \"g\", \"ml\" or \"cells\" (billion cells)."}},"required":["name"],"additionalProperties":false},"description":"Yeasts, e.g. [{\"name\": \"SafAle US-05\"}] (1 pack by default)."},"miscs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The misc ingredient (water agent, fining, spice, ...) from the brewer's ingredient library: its exact name (e.g. \"Gypsum\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount in unit, e.g. 5."},"unit":{"type":"string","enum":["g","ml","mg","tsp","tbsp","each"],"description":"\"g\" (default unless the library says otherwise), \"ml\", \"mg\", \"tsp\", \"tbsp\" or \"each\"."},"use":{"type":"string","enum":["mash","boil","whirlpool","primary","secondary","bottling"],"description":"\"boil\" (default), \"mash\", \"whirlpool\", \"primary\", \"secondary\" or \"bottling\"."},"time_min":{"type":"number","minimum":0,"description":"mash/boil/whirlpool: minutes, e.g. 15 for a fining 15 min before the end of the boil."},"day":{"type":"number","minimum":0,"description":"primary/secondary: fermentation day it goes in."}},"required":["name","amount"],"additionalProperties":false},"description":"Other additions (salts, finings, spices), e.g. [{\"name\": \"Gypsum\", \"amount\": 5, \"use\": \"mash\"}]."}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"recipe_id":{"type":"string","description":"Recipe (version group) id; find_recipes / copy_brew accept it."},"version":{"type":"string","description":"Recipe version, e.g. \"v2\"."},"planned_date":{"type":"string"},"brew_date":{"type":"string"},"ready_by_date":{"type":"string"}},"required":["id","name","status","recipe_id"]},"planned":{"type":"object","properties":{"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number"},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"abv_pct":{"type":"number"},"ibu":{"type":"number"},"color_ebc":{"type":"number"}},"description":"Planned stats of the recipe (absent while it has no fermentables)."},"batch_volume_l":{"type":"number"},"equipment":{"type":"object","properties":{"profile":{"type":"string","description":"Equipment profile the recipe is calculated with (absent: the recipe's own values)."},"brewhouse_efficiency_pct":{"type":"number"},"mash_efficiency_pct":{"type":"number"}},"description":"Equipment profile and efficiencies the planned values are calculated with."},"style_fit":{"type":"array","items":{"type":"string"},"description":"Planned values outside the style's range, e.g. \"IBU 62 is above the style range 40-50\". Absent when everything fits or no style is set."},"recipe":{"type":"object","additionalProperties":{},"description":"The recipe as stored (amounts in g, temperatures in °C) with entry ids."},"notes":{"type":"array","items":{"type":"string"}}},"required":["brew"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_recipe":{"post":{"operationId":"update_recipe","tags":["Actions: Brewing"],"summary":"Edit a brew's recipe","description":"Change a brew's recipe step by step without resending it: add, change, swap or remove ingredients (by name), set batch volume, boil time, efficiency, mash rests, fermentation stages, style, FG override, or load an equipment/mash/fermentation/water profile by name. target_og / target_ibu rescale malt / bittering hops to hit an OG or IBU (the editor's target modes). Send only what changes. Returns the new planned stats (OG/FG as SG, ABV %, IBU, color EBC), out-of-style warnings, the recipe with entry ids and notes on what changed. Example: swap Cascade for Citra → {\"brew\": \"#12\", \"change_ingredients\": [{\"ingredient\": \"Cascade\", \"replace_with\": \"Citra\"}]}. Name, dates, tags and status are update_brew / set_brew_status. Imported recipes must be converted first (convert_imported_brew).\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"add_fermentables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The fermentable (malt, sugar, extract) from the brewer's ingredient library: its exact name (e.g. \"Pilsner Malt\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount_g":{"type":"number","exclusiveMinimum":0,"description":"Amount in grams, e.g. 4500 for 4.5 kg."},"add_at":{"type":"string","enum":["mash","lauter","boil","fermentation"],"description":"When it goes in: \"mash\" (default), \"lauter\", \"boil\" or \"fermentation\"."}},"required":["name","amount_g"],"additionalProperties":false},"description":"Fermentables to add (same shape as in create_brew)."},"add_hops":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The hop from the brewer's ingredient library: its exact name (e.g. \"Citra\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount_g":{"type":"number","exclusiveMinimum":0,"description":"Amount in grams, e.g. 25."},"use":{"type":"string","enum":["boil","first_wort","mash","whirlpool","dry_hop"],"description":"\"boil\" (default), \"first_wort\", \"mash\", \"whirlpool\" (hopstand after flameout) or \"dry_hop\"."},"time_min":{"type":"number","minimum":0,"description":"boil/first_wort/mash: minutes before the end of the boil (e.g. 60 = bittering, 10 = flavor; default 60). whirlpool: minute after flameout it goes in (default 0)."},"day":{"type":"number","minimum":0,"description":"dry_hop only: fermentation day it goes in, e.g. 5."},"duration_days":{"type":"number","minimum":0,"description":"dry_hop only: contact days before it is removed, e.g. 3."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Alpha acid in % if it differs from the library value, e.g. 12.5."},"form":{"type":"string","enum":["pellet","whole","cryo","extract"],"description":"\"pellet\" (default), \"whole\", \"cryo\" or \"extract\"."}},"required":["name","amount_g"],"additionalProperties":false},"description":"Hop additions to add, e.g. [{\"name\": \"Mosaic\", \"amount_g\": 30, \"use\": \"whirlpool\", \"time_min\": 0}]."},"add_yeasts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The yeast from the brewer's ingredient library: its exact name (e.g. \"SafAle US-05\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount in unit (default 1)."},"unit":{"type":"string","enum":["pkg","g","ml","cells"],"description":"\"pkg\" (packs, default), \"g\", \"ml\" or \"cells\" (billion cells)."}},"required":["name"],"additionalProperties":false},"description":"Yeasts to add."},"add_miscs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"The misc ingredient (water agent, fining, spice, ...) from the brewer's ingredient library: its exact name (e.g. \"Gypsum\"; case and punctuation do not matter) or its ingredient id. Unknown names fail with candidates to pick from."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount in unit, e.g. 5."},"unit":{"type":"string","enum":["g","ml","mg","tsp","tbsp","each"],"description":"\"g\" (default unless the library says otherwise), \"ml\", \"mg\", \"tsp\", \"tbsp\" or \"each\"."},"use":{"type":"string","enum":["mash","boil","whirlpool","primary","secondary","bottling"],"description":"\"boil\" (default), \"mash\", \"whirlpool\", \"primary\", \"secondary\" or \"bottling\"."},"time_min":{"type":"number","minimum":0,"description":"mash/boil/whirlpool: minutes, e.g. 15 for a fining 15 min before the end of the boil."},"day":{"type":"number","minimum":0,"description":"primary/secondary: fermentation day it goes in."}},"required":["name","amount"],"additionalProperties":false},"description":"Other additions to add."},"change_ingredients":{"type":"array","items":{"type":"object","properties":{"ingredient":{"type":"string","minLength":1,"description":"The entry in this recipe: its entry id (from get_brew include [\"recipe\"]) or its name, e.g. \"Cascade\". If the name is used by several entries (e.g. a boil and a dry hop addition), pass the entry id."},"replace_with":{"type":"string","description":"Swap in another library ingredient of the same kind, keeping amount and timing unless you also change them, e.g. \"Citra\"."},"amount_g":{"type":"number","exclusiveMinimum":0,"description":"New amount in grams (fermentables, hops)."},"amount":{"type":"number","exclusiveMinimum":0,"description":"New amount in the entry's unit (yeasts, miscs)."},"use":{"type":"string","enum":["boil","first_wort","mash","whirlpool","dry_hop","primary","secondary","bottling"],"description":"New use (hops, miscs), same values as when adding."},"time_min":{"type":"number","minimum":0,"description":"New time in minutes (hops, miscs), meaning as when adding."},"day":{"type":"number","minimum":0,"description":"New fermentation day (dry hops, fermentation miscs)."},"duration_days":{"type":"number","minimum":0,"description":"New dry hop contact days."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"New alpha acid % (hops)."},"add_at":{"type":"string","enum":["mash","lauter","boil","fermentation"],"description":"New addition point (fermentables)."}},"required":["ingredient"],"additionalProperties":false},"description":"Change or swap existing entries, e.g. [{\"ingredient\": \"Cascade\", \"replace_with\": \"Citra\"}] or [{\"ingredient\": \"Pale Ale Malt\", \"amount_g\": 5500}]."},"remove_ingredients":{"type":"array","items":{"type":"string"},"description":"Entries to remove: entry ids or names (a name removes every entry with that name), e.g. [\"Crystal 60\"]."},"scale_ingredients":{"type":"boolean","description":"When batch_volume_l, efficiency_pct or equipment_profile change: true (default) scales the ingredient amounts (malt, hops, yeast, other additions, water) so OG and IBU stay the same, like the app's Scale batch; false only changes the value."},"style":{"type":"string","description":"Beer style: a BJCP 2021 style name or code (e.g. \"American IPA\", \"Hazy IPA\", \"German Pils\" or \"21A\"), or the name of one of the brewer's own styles. Unknown names fail with similar styles. Send \"none\" to clear it."},"equipment_profile":{"type":"string","description":"Name or id of one of the brewer's equipment profiles (e.g. \"Braumeister 20L\"). Sets batch volume, boil time and efficiency from the profile unless you also send them."},"mash_profile":{"type":"string","description":"Name or id of one of the brewer's mash profiles (e.g. \"Single infusion 67°C\"). Replaces the mash steps."},"fermentation_profile":{"type":"string","description":"Name or id of one of the brewer's fermentation profiles (e.g. \"Ale 19°C\"). Replaces the fermentation stages."},"water_source_profile":{"type":"string","description":"Name or id of one of the brewer's water profiles (e.g. \"Munich tap water\"). Used as the recipe's source water."},"water_target_profile":{"type":"string","description":"Name or id of one of the brewer's water profiles (e.g. \"Balanced\"). Used as the recipe's target water."},"batch_volume_l":{"type":"number","exclusiveMinimum":0,"maximum":10000,"description":"Batch volume in liters (into the fermenter), e.g. 20."},"boil_time_min":{"type":"number","minimum":0,"maximum":600,"description":"Boil time in minutes, e.g. 60."},"efficiency_pct":{"type":"number","minimum":1,"maximum":100,"description":"Brewhouse efficiency in %, e.g. 72."},"mash_steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Step name, e.g. \"Saccharification rest\" (default \"Rest 1\", \"Rest 2\", ...)."},"type":{"type":"string","enum":["infusion","temperature","decoction"],"description":"\"infusion\" (default for the first step), \"temperature\" (heated, default for later steps) or \"decoction\"."},"temp":{"type":"number","description":"Rest temperature in temp_unit (default °C), e.g. 67."},"duration_min":{"type":"number","minimum":0,"description":"Rest time in minutes, e.g. 60."}},"required":["temp","duration_min"],"additionalProperties":false},"description":"The full list of mash rests in order; replaces the current steps."},"fermentation_stages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Stage name, e.g. \"Primary\" (default from type)."},"type":{"type":"string","enum":["primary","secondary","tertiary","cold_crash","conditioning","carbonation"],"description":"\"primary\" (default for the first stage), \"secondary\", \"tertiary\", \"cold_crash\", \"conditioning\" or \"carbonation\"."},"temp":{"type":"number","description":"Temperature in temp_unit (default °C), e.g. 19."},"duration_days":{"type":"number","minimum":0,"description":"Duration in days, e.g. 10."}},"required":["temp","duration_days"],"additionalProperties":false},"description":"The full list of fermentation stages in order; replaces the current stages."},"temp_unit":{"type":"string","enum":["c","f"],"description":"Unit of the temperatures you send: \"c\" (°C, default) or \"f\" (°F)."},"fg_override_sg":{"anyOf":[{"type":"number","minimum":0.98,"maximum":1.1},{"type":"null"}],"description":"Planned FG to use instead of the one calculated from yeast attenuation, as SG (e.g. 1.012). null removes the override."},"target_og":{"type":"number","description":"OG to hit, as the brew page shows it, in gravity_unit (SG by default, e.g. 1.052; or °P with gravity_unit \"plato\", e.g. 12.9). Scales the malt amounts and keeps their shares, like the recipe editor's target OG (percentage mode stays on)."},"target_ibu":{"type":"number","minimum":0,"maximum":200,"description":"IBU to hit, as the brew page shows it, e.g. 35. Scales every IBU-giving hop addition (all boil times incl. late ones, first wort, whirlpool; not dry hops) keeping each one's share of the IBU, like the recipe editor's IBU target (stays on). Applied after ingredient changes in the same call."},"gravity_unit":{"type":"string","enum":["sg","plato"],"description":"Unit of the gravity values you send: \"sg\" (specific gravity, e.g. 1.012; default) or \"plato\" (°P, e.g. 3.1)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"recipe_id":{"type":"string","description":"Recipe (version group) id; find_recipes / copy_brew accept it."},"version":{"type":"string","description":"Recipe version, e.g. \"v2\"."},"planned_date":{"type":"string"},"brew_date":{"type":"string"},"ready_by_date":{"type":"string"}},"required":["id","name","status","recipe_id"]},"planned":{"type":"object","properties":{"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number"},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"abv_pct":{"type":"number"},"ibu":{"type":"number"},"color_ebc":{"type":"number"}},"description":"Planned stats of the recipe (absent while it has no fermentables)."},"batch_volume_l":{"type":"number"},"equipment":{"type":"object","properties":{"profile":{"type":"string","description":"Equipment profile the recipe is calculated with (absent: the recipe's own values)."},"brewhouse_efficiency_pct":{"type":"number"},"mash_efficiency_pct":{"type":"number"}},"description":"Equipment profile and efficiencies the planned values are calculated with."},"style_fit":{"type":"array","items":{"type":"string"},"description":"Planned values outside the style's range, e.g. \"IBU 62 is above the style range 40-50\". Absent when everything fits or no style is set."},"recipe":{"type":"object","additionalProperties":{},"description":"The recipe after the change (amounts in g, °C) with entry ids."},"notes":{"type":"array","items":{"type":"string"},"description":"What changed."}},"required":["brew","notes"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_brew":{"post":{"operationId":"update_brew","tags":["Actions: Brewing"],"summary":"Rename, date, tag or pin a brew","description":"Change a brew's details (not its recipe): name, description, planned brew day, actual brew date, ready-by date, tags, pin. Send only what changes; null clears a date. Setting planned_date on an idea also makes it \"planned\" (it gets a batch number), which is how you plan a brew for a day. For other status changes use set_brew_status; for ingredients and process use update_recipe.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"name":{"type":"string","minLength":1,"maxLength":200,"description":"New name, e.g. \"Citra Pale Ale v2\"."},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"description":"New description; null clears it."},"planned_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Planned brew day (YYYY-MM-DD, e.g. \"2026-11-21\")."},{"type":"null"}],"description":"Planned brew day as YYYY-MM-DD (e.g. \"2026-11-21\"); null clears it. Plans an idea."},"brew_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Actual brew day (for brews already brewed) (YYYY-MM-DD, e.g. \"2026-11-07\")."},{"type":"null"}],"description":"Actual brew day (for brews already brewed) (YYYY-MM-DD, e.g. \"2026-11-07\")."},"ready_by_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the beer must be ready by (YYYY-MM-DD, e.g. \"2026-12-24\")."},{"type":"null"}],"description":"Date the beer must be ready by (YYYY-MM-DD, e.g. \"2026-12-24\")."},"ready_by_note":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"What it must be ready for, e.g. \"Christmas party\"; null clears it."},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"description":"Replace all tags, e.g. [\"hoppy\"]. [] removes all."},"add_tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"description":"Tags to add, keeping the others, e.g. [\"competition\"]."},"remove_tags":{"type":"array","items":{"type":"string"},"description":"Tags to remove."},"pinned":{"type":"boolean","description":"Pin (true) or unpin (false) the brew in the sidebar."},"brew_type":{"type":"string","enum":["all_grain","partial_mash","extract"],"description":"Brew type."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"recipe_id":{"type":"string","description":"Recipe (version group) id; find_recipes / copy_brew accept it."},"version":{"type":"string","description":"Recipe version, e.g. \"v2\"."},"planned_date":{"type":"string"},"brew_date":{"type":"string"},"ready_by_date":{"type":"string"}},"required":["id","name","status","recipe_id"]},"tags":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean"},"notes":{"type":"array","items":{"type":"string"}}},"required":["brew"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/set_brew_status":{"post":{"operationId":"set_brew_status","tags":["Actions: Brewing"],"summary":"Change a brew's status","description":"Move a brew through its lifecycle: idea → planned → brewing → fermenting → conditioning → completed → archived. The app's side effects happen as in the UI: planning assigns a batch number, brewing sets the brew date (today unless you pass date), conditioning records its start, completing adds the beer to tap lists set to auto-add. Unusual moves (backwards, skipping steps, archiving early) return needs_confirmation with the app's warning and change nothing; repeat with confirm: true after checking with the user. Brew-day measurements, packaging and cellar moves are separate tools.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"],"description":"New status, e.g. \"fermenting\"."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"For \"planned\": the planned brew day. For \"brewing\" and later: the actual brew date if it is not today. Ignored otherwise (YYYY-MM-DD, e.g. \"2026-11-21\")."},"confirm":{"type":"boolean","description":"true to do an unusual move (backwards, skipping steps, archiving early) after a needs_confirmation answer."}},"required":["brew","status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"recipe_id":{"type":"string","description":"Recipe (version group) id; find_recipes / copy_brew accept it."},"version":{"type":"string","description":"Recipe version, e.g. \"v2\"."},"planned_date":{"type":"string"},"brew_date":{"type":"string"},"ready_by_date":{"type":"string"}},"required":["id","name","status","recipe_id"]},"previous_status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"changes":{"type":"array","items":{"type":"string"},"description":"Side effects, e.g. batch number assigned, brew date set."},"warning":{"type":"string","description":"The app's warning for an unusual move that you confirmed."},"next_step":{"type":"string","description":"Something to do next, e.g. move the cellar plan when the brew day differs from the planned day."}},"required":["brew","previous_status"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/copy_brew":{"post":{"operationId":"copy_brew","tags":["Actions: Brewing"],"summary":"Brew again, new version or copy as new recipe","description":"Start a new brew from an existing one. mode \"brew_again\" (default): the next batch of the same recipe version, status planned with a new batch number. \"new_version\": the next version of the recipe (v2, v3, ...) as an idea, to change with update_recipe; version_notes says what changes. \"new_recipe\": an independent copy under a new name (no version link). It copies the brew as it is now (including earlier update_recipe changes). from accepts a brew (id, batch number) or a recipe (name, recipe id; its newest brew is copied). Pass planned_date to plan the new brew right away. Fails with LIMIT_REACHED when the free plan's brew limit is full.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"The brew or recipe to copy: a brew id or batch number (e.g. \"#12\"), or a recipe name or id (e.g. \"Citra Pale Ale\"; its newest brew is used)."},"mode":{"type":"string","enum":["brew_again","new_version","new_recipe"],"description":"\"brew_again\" (default), \"new_version\" or \"new_recipe\"."},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name of the copy. Required for new_recipe unless \"<name> (copy)\" is fine."},"version_notes":{"type":"string","maxLength":2000,"description":"new_version: what changes in this version, e.g. \"More late hops, less crystal\"."},"planned_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Planned brew day of the new brew (YYYY-MM-DD, e.g. \"2026-11-21\")."}},"required":["from"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"recipe_id":{"type":"string","description":"Recipe (version group) id; find_recipes / copy_brew accept it."},"version":{"type":"string","description":"Recipe version, e.g. \"v2\"."},"planned_date":{"type":"string"},"brew_date":{"type":"string"},"ready_by_date":{"type":"string"}},"required":["id","name","status","recipe_id"]},"copied_from":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name"]}},"required":["brew","copied_from"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/share_brew":{"post":{"operationId":"share_brew","tags":["Actions: Brewing"],"summary":"Turn a brew's share link on or off","description":"Create (enabled: true, default) or remove (enabled: false) the public read-only link to a brew's recipe and results. Anyone with the link can view the recipe and copy it to their own BrewForge account (there is no sharing with one specific person: give them this link); removing the link makes it stop working. Calling it again with enabled: true keeps the existing link. Returns share_url (absent when off).\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"enabled":{"type":"boolean","description":"true (default) to share, false to remove the link."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"shared":{"type":"boolean"},"share_url":{"type":"string","description":"Public link to the brew; give it to the user."}},"required":["brew","shared"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/convert_imported_brew":{"post":{"operationId":"convert_imported_brew","tags":["Actions: Brewing"],"summary":"Make an imported recipe editable","description":"Imported recipes (BeerXML, Brewfather, ...) keep the source program's numbers (OG, IBU, volumes) and can't be edited until they use BrewForge's own calculations. mode \"convert\" (default) switches this brew to BrewForge calculations in place; \"fork\" keeps the import untouched and creates a new editable version. Afterwards the stats may differ slightly from the imported ones. Returns the editable brew; then use update_recipe on it.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"mode":{"type":"string","enum":["convert","fork"],"description":"\"convert\" (default, in place) or \"fork\" (new version, import kept)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"recipe_id":{"type":"string","description":"Recipe (version group) id; find_recipes / copy_brew accept it."},"version":{"type":"string","description":"Recipe version, e.g. \"v2\"."},"planned_date":{"type":"string"},"brew_date":{"type":"string"},"ready_by_date":{"type":"string"}},"required":["id","name","status","recipe_id"]},"planned":{"type":"object","additionalProperties":{"type":"number"},"description":"Planned stats with BrewForge calculations (SG, %, IBU, EBC)."}},"required":["brew"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/import_recipe":{"post":{"operationId":"import_recipe","tags":["Actions: Brewing"],"summary":"Import a recipe (BeerXML or MMuM)","description":"Import recipes from file content: BeerXML (<RECIPES>... from BeerSmith, Brewfather, Little Bock etc., one or more recipes) or MMuM JSON (Maische Malz und Mehr / Kleiner Brauhelfer). Each recipe becomes a new idea in the recipe book that keeps the source program's numbers; call convert_imported_brew before editing one with update_recipe. Pass the file's text as content; format is detected when omitted. MMuM files without batch volume or brewhouse yield need batch_volume_l / efficiency_pct (the error says which).\n\nNeeds the plan feature `import_export`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","feature":"import_export","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":5000000,"description":"The complete file content as text (XML for BeerXML, JSON for MMuM)."},"format":{"type":"string","enum":["beerxml","mmum"],"description":"\"beerxml\" or \"mmum\"; detected from the content when omitted."},"batch_volume_l":{"type":"number","exclusiveMinimum":0,"maximum":10000,"description":"MMuM only: cast-out volume in liters when the file has none, e.g. 20."},"efficiency_pct":{"type":"number","minimum":1,"maximum":100,"description":"MMuM only: brewhouse yield (Sudhausausbeute) in % when the file has none, e.g. 70."}},"required":["content"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"imported":{"type":"integer"},"brews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"style":{"type":"string"},"batch_volume_l":{"type":"number"},"og_sg":{"type":"number","description":"OG as the source program calculated it."}},"required":["id","name"]}},"errors":{"type":"array","items":{"type":"string"},"description":"Recipes or parts that could not be imported."}},"required":["imported","brews"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/export_brew":{"post":{"operationId":"export_brew","tags":["Actions: Brewing"],"summary":"Export a brew (BeerXML, JSON, PDF sheets)","description":"Export one brew. \"beerxml\" (recipe for other brewing software) and \"json\" (everything BrewForge stores, incl. measurements and readings) return the file text in content. The printable sheets \"recipe_pdf\", \"brewday_pdf\" (brew-day checklist) and \"fermentation_pdf\" (log sheet) return a download_url that works without login for 15 minutes; give it to the user, don't fetch it yourself unless you need the PDF bytes.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"format":{"type":"string","enum":["beerxml","json","recipe_pdf","brewday_pdf","fermentation_pdf"],"description":"\"beerxml\", \"json\", \"recipe_pdf\", \"brewday_pdf\" or \"fermentation_pdf\"."}},"required":["brew","format"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"format":{"type":"string","enum":["beerxml","json","recipe_pdf","brewday_pdf","fermentation_pdf"]},"filename":{"type":"string"},"content":{"type":"string","description":"File text (beerxml, json)."},"download_url":{"type":"string","description":"PDF link, valid until expires_at."},"expires_at":{"type":"string"}},"required":["brew","format"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_brew":{"post":{"operationId":"delete_brew","tags":["Actions: Brewing"],"summary":"Delete a brew","description":"Permanently delete one brew with its readings, notes, evaluations and cellar stays (planned ones too). Without confirm: true it only returns what would be deleted (deleted_with_it) and what stays (devices are detached, tap list entries stay as typed-in beers). Refused while the cellar still holds beer of it (a keg with volume or filled bottles/cans): empty or free those first. To keep the brew out of lists without deleting it, set its status to archived instead.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"destructive","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_brew_day_plan":{"post":{"operationId":"get_brew_day_plan","tags":["Actions: Brewing"],"summary":"Get the brew day plan","description":"What to do on brew day, as the app's brew day tab computes it: water volumes (strike/sparge in L), strike temperature (°C), water additions, grain bill, mash steps, boil time, hop and other additions in order, yeast and pitching temperature, and every brew day measurement with its target and the value recorded so far (measurements[].field is the parameter name for record_brew_measurements). Once measurements exist it also returns the batch efficiencies (mash, brewhouse, Sudhausausbeute in %) next to the planned ones. Read-only. Reference the brew by id, batch number or exact name.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"planned":{"type":"object","properties":{"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number"},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"abv_pct":{"type":"number"},"ibu":{"type":"number"},"color_ebc":{"type":"number"},"batch_volume_l":{"type":"number"},"fermenter_volume_l":{"type":"number"}}},"planned_efficiency":{"type":"object","properties":{"mash_efficiency_pct":{"type":"number"},"brewhouse_efficiency_pct":{"type":"number"},"sudhausausbeute_pct":{"type":"number"}}},"measurements":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Input field of record_brew_measurements for this value."},"unit":{"type":"string","description":"c = °C, l = litres, sg = specific gravity, ph, min = minutes."},"phase":{"type":"string"},"target":{"type":"number"},"measured":{"type":"number"},"off_by":{"type":"number","description":"measured - target, in unit."},"on_target":{"type":"boolean","description":"Within the app's tolerance (gravity ±0.002, volume ±3 %, temperature ±1 °C, pH ±0.1)."}},"required":["field","unit","phase"]}},"batch":{"type":"object","properties":{"mash_efficiency_pct":{"type":"number"},"brewhouse_efficiency_pct":{"type":"number"},"sudhausausbeute_pct":{"type":"number"},"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number"},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"abv_pct":{"type":"number"},"apparent_attenuation_pct":{"type":"number"},"ibu":{"type":"number"},"boil_off_l_per_h":{"type":"number"},"packaged_volume_l":{"type":"number"}},"description":"Batch values the app derives from the measurements (planned values where nothing was measured yet)."}},"required":["brew","measurements"],"additionalProperties":true}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/record_brew_measurements":{"post":{"operationId":"record_brew_measurements","tags":["Actions: Brewing"],"summary":"Record brew day measurements","description":"Record what was measured on brew day or at the end of fermentation: strike water, mash pH, pre-boil gravity/volume, boil time, post-boil volume, OG, fermenter volume, pitching temperature, final gravity, peak fermentation temperature. Send only the values you have: a value you send replaces the stored one, the others stay as they are, null clears one. Gravities default to SG (gravity_unit \"plato\" for °P), temperatures to °C, volumes are litres. Returns the recorded values, how each compares with its target, and the batch values the app derives (mash/brewhouse efficiency %, ABV, attenuation). For gravity readings during fermentation use log_fermentation_reading instead; this does not change the brew status (set_brew_status moves it to fermenting). Targets: get_brew_day_plan.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"strike_water_temp":{"type":["number","null"],"description":"Strike water temperature, e.g. 72 (°C) or °F with temp_unit \"f\". Send null to clear a recorded value."},"strike_water_volume_l":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Strike water in litres, e.g. 18. Send null to clear a recorded value."},"mash_ph":{"anyOf":[{"type":"number","minimum":2,"maximum":9},{"type":"null"}],"description":"Mash pH, e.g. 5.4. Send null to clear a recorded value."},"sparge_water_volume_l":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Sparge water in litres, e.g. 12. Send null to clear a recorded value."},"first_runnings_gravity":{"type":["number","null"],"description":"Gravity of the first runnings, e.g. 1.072 (SG) or the °P value with gravity_unit \"plato\". Send null to clear a recorded value."},"pre_boil_gravity":{"type":["number","null"],"description":"Pre-boil gravity, e.g. 1.044 (SG) or the °P value with gravity_unit \"plato\". Send null to clear a recorded value."},"pre_boil_volume_l":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Wort in the kettle before the boil in litres, e.g. 27. Send null to clear a recorded value."},"boil_time_min":{"anyOf":[{"type":"integer","minimum":0,"maximum":600},{"type":"null"}],"description":"Actual boil time in minutes, e.g. 60. Send null to clear a recorded value."},"post_boil_volume_l":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Wort after the boil (hot) in litres, e.g. 23.5. Send null to clear a recorded value."},"post_boil_ph":{"anyOf":[{"type":"number","minimum":2,"maximum":9},{"type":"null"}],"description":"pH after the boil, e.g. 5.4. Send null to clear a recorded value."},"pre_dilution_gravity":{"type":["number","null"],"description":"Gravity before topping up with water (recipes with a fermenter top-up), e.g. 1.060 (SG) or the °P value with gravity_unit \"plato\". Send null to clear a recorded value."},"pre_dilution_volume_l":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Volume before topping up in litres, e.g. 18. Send null to clear a recorded value."},"og":{"type":["number","null"],"description":"Original gravity into the fermenter, e.g. 1.052 (SG) or the °P value with gravity_unit \"plato\". Send null to clear a recorded value."},"fermenter_volume_l":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Volume into the fermenter in litres, e.g. 21. Send null to clear a recorded value."},"pitching_temp":{"type":["number","null"],"description":"Wort temperature when the yeast was pitched, e.g. 18 (°C) or °F with temp_unit \"f\". Send null to clear a recorded value."},"fg":{"type":["number","null"],"description":"Final gravity at the end of fermentation, e.g. 1.011 (SG) or the °P value with gravity_unit \"plato\". Send null to clear a recorded value."},"fermentation_peak_temp":{"type":["number","null"],"description":"Highest beer temperature during fermentation (priming sugar uses it), e.g. 21 (°C) or °F with temp_unit \"f\". Send null to clear a recorded value."},"gravity_unit":{"type":"string","enum":["sg","plato"],"description":"Unit of the gravity values you send: \"sg\" (specific gravity, e.g. 1.012; default) or \"plato\" (°P, e.g. 3.1)."},"temp_unit":{"type":"string","enum":["c","f"],"description":"Unit of the temperatures you send: \"c\" (°C, default) or \"f\" (°F)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"recorded":{"type":"object","additionalProperties":{"type":"number"},"description":"Every measurement now stored on the brew, including ones recorded earlier, in canonical units (_c °C, _l litres, _sg SG)."},"changes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":["number","null"],"description":"Stored value in canonical units; null = cleared."},"target":{"type":"number"},"on_target":{"type":"boolean"}},"required":["field","value"]}},"batch":{"type":"object","properties":{"mash_efficiency_pct":{"type":"number"},"brewhouse_efficiency_pct":{"type":"number"},"sudhausausbeute_pct":{"type":"number"},"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number"},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"abv_pct":{"type":"number"},"apparent_attenuation_pct":{"type":"number"},"ibu":{"type":"number"},"boil_off_l_per_h":{"type":"number"},"packaged_volume_l":{"type":"number"}},"description":"Batch values the app derives from the measurements (planned values where nothing was measured yet)."},"planned_efficiency":{"type":"object","properties":{"mash_efficiency_pct":{"type":"number"},"brewhouse_efficiency_pct":{"type":"number"},"sudhausausbeute_pct":{"type":"number"}}},"status_note":{"type":"string","description":"Recording measurements never changes the brew status; this says the status and the usual next one (set_brew_status)."}},"required":["brew","recorded","changes","status_note"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/deduct_brew_ingredients":{"post":{"operationId":"deduct_brew_ingredients","tags":["Actions: Brewing"],"summary":"Deduct a brew's ingredients from stock","description":"Take the ingredients a brew uses out of the inventory, as \"Deduct from inventory\" on the brew day tab does: each recipe ingredient is matched to a stock lot by name (hops also by form and alpha acid) and the recipe amount is deducted; the brew remembers what was deducted, so it is never deducted twice. Default: every ingredient with enough stock. ingredients limits it to some (names as in the recipe); naming an ingredient also deducts it when the stock is short (the lot goes to 0). dry_run: true only shows what would happen. undo: true puts deducted ingredients back into stock (all, or the named ones). Amounts in g for fermentables and hops, else the recipe unit.\n\nNeeds the plan feature `inventory`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"inventory:write","feature":"inventory","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"ingredients":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Only these recipe ingredients, by name, e.g. [\"Pilsner Malt\", \"Saaz\"]. Default: all."},"undo":{"type":"boolean","description":"true = restore deducted ingredients to stock instead of deducting."},"dry_run":{"type":"boolean","description":"true = change nothing, only report what would be deducted or restored."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"ingredients":{"type":"array","items":{"type":"object","properties":{"ingredient":{"type":"string"},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"amount":{"type":"number","description":"Amount of this ingredient the recipe needs (still to deduct, or deducted)."},"unit":{"type":"string","description":"g for fermentables and hops, else the recipe unit."},"status":{"type":"string","enum":["deducted","already_deducted","restored","would_deduct","would_restore","not_in_stock","not_enough_stock","not_deducted","cannot_restore"],"description":"What happened (or would happen) to this ingredient."},"lot":{"type":"string","description":"Stock lot used (ingredient name and supplier/lot number)."},"in_stock":{"type":"number","description":"Quantity of the lot before this call, in unit."}},"required":["ingredient","type","amount","unit","status"]}},"summary":{"type":"string"}},"required":["brew","ingredients","summary"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/log_fermentation_reading":{"post":{"operationId":"log_fermentation_reading","tags":["Actions: Brewing"],"summary":"Log a fermentation reading","description":"Add a fermentation reading (gravity, temperature, pH, pressure and/or a comment) to a brew, as from a hydrometer or refractometer check. Gravity defaults to SG (send gravity_unit \"plato\" for °P), temperature to °C. Stored in canonical units (SG, °C, psi); it shows up in the brew's fermentation chart. Several readings at once: send readings: [{gravity, temp, at}, ...] instead of the single fields. To correct a reading, send reading_id (ids come from get_fermentation) with only the fields to change; null clears a field. The final gravity of a finished beer is recorded with record_brew_measurements (fg). Reference the brew by id, batch number or exact name.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"gravity":{"type":["number","null"],"description":"Measured gravity, e.g. 1.012 (SG) or 3.1 (with gravity_unit \"plato\")."},"temp":{"type":["number","null"],"description":"Beer temperature, e.g. 19.5 (°C) or 67 (with temp_unit \"f\")."},"ph":{"anyOf":[{"type":"number","minimum":2,"maximum":8},{"type":"null"}],"description":"pH, e.g. 4.3."},"pressure":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Head pressure, e.g. 12 (psi) or 0.8 (with pressure_unit \"bar\")."},"comment":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Free text, e.g. \"krausen dropped\"."},"at":{"type":"string","format":"date-time","description":"When it was measured, ISO 8601 with time zone, e.g. 2026-11-11T08:30:00+01:00 (use Z for UTC when the user's zone is unknown). Default: now."},"readings":{"type":"array","items":{"type":"object","properties":{"gravity":{"type":["number","null"],"description":"Measured gravity, e.g. 1.012 (SG) or 3.1 (with gravity_unit \"plato\")."},"temp":{"type":["number","null"],"description":"Beer temperature, e.g. 19.5 (°C) or 67 (with temp_unit \"f\")."},"ph":{"anyOf":[{"type":"number","minimum":2,"maximum":8},{"type":"null"}],"description":"pH, e.g. 4.3."},"pressure":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Head pressure, e.g. 12 (psi) or 0.8 (with pressure_unit \"bar\")."},"comment":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Free text, e.g. \"krausen dropped\"."},"at":{"type":"string","format":"date-time","description":"When it was measured, ISO 8601 with time zone, e.g. 2026-11-11T08:30:00+01:00 (use Z for UTC when the user's zone is unknown). Default: now."}},"additionalProperties":false},"minItems":1,"maxItems":500,"description":"Several readings at once (up to 500), each with gravity/temp/ph/pressure/comment/at. Units apply to all of them."},"reading_id":{"type":"string","description":"Id of an existing reading to correct instead of adding a new one."},"gravity_unit":{"type":"string","enum":["sg","plato"],"description":"Unit of the gravity values you send: \"sg\" (specific gravity, e.g. 1.012; default) or \"plato\" (°P, e.g. 3.1)."},"temp_unit":{"type":"string","enum":["c","f"],"description":"Unit of the temperatures you send: \"c\" (°C, default) or \"f\" (°F)."},"pressure_unit":{"type":"string","enum":["psi","bar"],"description":"Unit of pressure: \"psi\" (default) or \"bar\"."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"]},"reading":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"gravity_sg":{"type":"number"},"gravity_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"temp_c":{"type":"number"},"ph":{"type":"number"},"pressure_psi":{"type":"number"},"comment":{"type":"string"}},"required":["id","at"],"description":"The reading added or corrected (single reading)."},"readings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"gravity_sg":{"type":"number"},"gravity_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"temp_c":{"type":"number"},"ph":{"type":"number"},"pressure_psi":{"type":"number"},"comment":{"type":"string"}},"required":["id","at"]},"description":"The readings added (when readings[] was sent)."},"readings_count":{"type":"integer","description":"Readings the brew has now."}},"required":["brew","readings_count"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_fermentation":{"post":{"operationId":"get_fermentation","tags":["Actions: Brewing"],"summary":"Get fermentation status and readings","description":"How a brew's fermentation is going, as its fermentation tab shows it: OG, expected FG, current gravity, apparent attenuation and ABV so far, whether the gravity is stable (finished), the current speed and the projected time to reach FG, plus the newest readings with their ids (for corrections with log_fermentation_reading reading_id, or delete_fermentation_readings). Use it to answer \"is it done?\": state \"stable\" means the gravity changed at most 0.001 over the last day. All gravities in SG, temperatures in °C.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"readings_limit":{"type":"integer","minimum":0,"maximum":500,"description":"How many of the newest readings to list (default 20, 0 = none)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"state":{"type":"string","enum":["no_readings","active","slowing","stable","final_gravity_recorded"],"description":"no_readings; active = gravity still dropping; slowing = dropping at under half its peak speed; stable = gravity unchanged (±0.001) over the last day, i.e. finished; final_gravity_recorded = FG was entered."},"og_sg":{"type":"number"},"og_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"og_source":{"type":"string","enum":["measured","planned"]},"expected_fg_sg":{"type":"number"},"expected_fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"fg_sg":{"type":"number","description":"Recorded FG (record_brew_measurements)."},"fg_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"current_gravity_sg":{"type":"number"},"current_gravity_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"latest_reading_at":{"type":"string"},"apparent_attenuation_pct":{"type":"number","description":"Apparent attenuation as the app shows it, from gravity points: (OG - current) / (OG - 1) in SG. Quote this; a ratio of °P values differs slightly."},"abv_pct":{"type":"number"},"speed_sg_per_day":{"type":"number","description":"Current gravity drop per day (SG), positive while dropping."},"projected_fg_at":{"type":"string","description":"When the expected FG will be reached at the current rate."},"projection_unavailable":{"type":"string","description":"Why there is no projected_fg_at, e.g. insufficient_recent_readings (needs a sensor's frequent readings: 10+ in the last 24 h over 36 h+) or target_reached."},"peak_temp_c":{"type":"number"},"days_active":{"type":"number"},"readings_total":{"type":"integer"},"readings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"gravity_sg":{"type":"number"},"gravity_plato":{"type":"number","description":"Same gravity in °Plato (only when the user reads gravity in °Plato; the _sg value stays canonical)."},"temp_c":{"type":"number"},"ph":{"type":"number"},"pressure_psi":{"type":"number"},"comment":{"type":"string"}},"required":["id","at"]}}},"required":["brew","state","readings_total","readings"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_fermentation_readings":{"post":{"operationId":"delete_fermentation_readings","tags":["Actions: Brewing"],"summary":"Delete fermentation readings","description":"Delete one or more fermentation readings of a brew by id (e.g. a wrong hydrometer entry or sensor outliers). Without confirm: true it only lists what would be deleted. To fix a value instead, use log_fermentation_reading with reading_id. Reading ids come from get_fermentation.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"destructive","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"reading_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000,"description":"Ids of the readings to delete, from get_fermentation, e.g. [\"3f2c…\"]."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["brew","reading_ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/plan_carbonation":{"post":{"operationId":"plan_carbonation","tags":["Actions: Brewing"],"summary":"Plan carbonation (priming sugar or keg pressure)","description":"Work out how to carbonate a brew and save the plan on its fermentation tab, calculated as the app does it. method \"priming\" (default): grams of priming sugar for the beer volume, from target CO2 volumes, sugar type and beer temperature (default: the peak fermentation temperature). method \"force_carbonation\": regulator pressure (psi and bar) for the target CO2 at the serving temperature. Without target_co2_volumes it keeps the saved target or uses the style's typical value. The beer volume is the packaged volume, else the measured fermenter volume minus losses, else the planned volume; send beer_volume_l to override. Temperatures default to °C. Calling it again with only some fields keeps the rest of the saved plan.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"method":{"type":"string","enum":["priming","force_carbonation"],"description":"\"priming\" (sugar in bottles/keg) or \"force_carbonation\" (CO2 from a regulator). Default: the saved method, else \"priming\"."},"target_co2_volumes":{"type":"number","minimum":1,"maximum":5.1,"description":"Target carbonation in volumes of CO2, e.g. 2.4."},"sugar_type":{"type":"string","enum":["table_sugar","corn_sugar","dme","honey"],"description":"Priming sugar: \"table_sugar\" (default), \"corn_sugar\", \"dme\" or \"honey\"."},"beer_temp":{"type":"number","description":"Warmest temperature the beer reached after fermentation, for residual CO2 (priming), e.g. 20."},"serving_temp":{"type":"number","description":"Serving/keg temperature (force carbonation), e.g. 4."},"temp_unit":{"type":"string","enum":["c","f"],"description":"Unit of the temperatures you send: \"c\" (°C, default) or \"f\" (°F)."},"beer_volume_l":{"type":"number","exclusiveMinimum":0,"maximum":5000,"description":"Litres of beer to prime, e.g. 19. Default: from the brew (see description)."},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Free text saved with the plan; null clears it."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"method":{"type":"string","enum":["priming","force_carbonation"]},"target_co2_volumes":{"type":"number"},"style_range_co2_volumes":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"]},"sugar_type":{"type":"string"},"sugar_g":{"type":"number","description":"Priming sugar for the whole beer volume, grams."},"beer_volume_l":{"type":"number"},"beer_volume_source":{"type":"string","enum":["packaged","fermenter","planned","given"],"description":"packaged = packaged volume; fermenter = measured fermenter volume minus fermenter loss; planned = recipe plan; given = beer_volume_l."},"beer_temp_c":{"type":"number"},"serving_temp_c":{"type":"number"},"regulator_psi":{"type":"number"},"regulator_bar":{"type":"number"},"notes":{"type":"string"}},"required":["brew","method","target_co2_volumes","style_range_co2_volumes"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_brew_note":{"post":{"operationId":"save_brew_note","tags":["Actions: Brewing"],"summary":"Add or edit a brew note","description":"Add a timestamped note to a brew's log (what happened, a problem, an adjustment, a tasting impression, a reminder), or edit one. To add, send brew and text (type defaults to \"note\", time to now). To edit, also send note_id (from list_brew_notes) and only the fields to change. Measurements belong in record_brew_measurements or log_fermentation_reading, not in notes.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"text":{"type":"string","minLength":1,"maxLength":5000,"description":"The note, e.g. \"Mash pH came in low, added 2 g chalk\". Required when adding."},"type":{"type":"string","enum":["note","observation","issue","adjustment","reminder"],"description":"\"note\" (default), \"observation\", \"issue\" (something went wrong), \"adjustment\" (a change you made) or \"reminder\"."},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"],"description":"Brewing phase it belongs to, e.g. \"mash\" or \"fermentation\". Optional."},"at":{"type":"string","format":"date-time","description":"When it happened, ISO 8601 with time zone, e.g. 2026-11-11T10:15:00+01:00. Default: now."},"note_id":{"type":"string","description":"Id of an existing note to edit instead of adding a new one."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"note":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string","description":"ISO 8601 timestamp."},"type":{"type":"string","enum":["note","observation","issue","adjustment","reminder"]},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"]},"text":{"type":"string"}},"required":["id","at","type","text"]},"notes_count":{"type":"integer"}},"required":["brew","note","notes_count"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/list_brew_notes":{"post":{"operationId":"list_brew_notes","tags":["Actions: Brewing"],"summary":"List a brew's notes","description":"The notes of a brew's log, newest first, with their ids (for save_brew_note note_id or delete_brew_note). Filter by type or phase.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"type":{"type":"string","enum":["note","observation","issue","adjustment","reminder"],"description":"Only notes of this type, e.g. \"issue\"."},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"],"description":"Only notes of this phase, e.g. \"fermentation\"."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 20)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string","description":"ISO 8601 timestamp."},"type":{"type":"string","enum":["note","observation","issue","adjustment","reminder"]},"phase":{"type":"string","enum":["planning","mash","boil","fermentation","conditioning","packaging"]},"text":{"type":"string"}},"required":["id","at","type","text"]}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_brew_note":{"post":{"operationId":"delete_brew_note","tags":["Actions: Brewing"],"summary":"Delete a brew note","description":"Delete one note from a brew's log. Without confirm: true it only shows the note that would be deleted.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"destructive","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"note_id":{"type":"string","description":"Id of the note, from list_brew_notes."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["brew","note_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/set_brew_custom_fields":{"post":{"operationId":"set_brew_custom_fields","tags":["Actions: Brewing"],"summary":"Set custom field values on a brew","description":"Fill in the brewer's own custom fields on a brew (fields they defined in settings, e.g. \"Water source\" or \"Hop lot\"). values maps field name (or id) to its value, e.g. {\"Water source\": \"tap\", \"Mash tun loss L\": 1.2}; null clears a value. Send values: {} to only list the fields with their type, allowed choices and current values. Defining new fields is not done here.\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"values":{"type":"object","additionalProperties":{"type":["string","number","boolean","null"]},"description":"Field name or id → value: text/select/date/url as string, number/integer as number, boolean as true/false, null clears. E.g. {\"Water source\": \"tap\"}."}},"required":["brew","values"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"text, number, integer, date (YYYY-MM-DD), time (HH:MM), datetime, boolean, select, url."},"unit":{"type":"string"},"choices":{"type":"array","items":{"type":"string"},"description":"Allowed values of a select field."},"placement":{"type":"string","description":"Where the brew page shows it (brew_details, brew_day, fermentation, packaging, tasting)."},"value":{"type":["string","number","boolean"],"description":"Current value; missing = not set."}},"required":["id","name","type"]}},"changed":{"type":"array","items":{"type":"string"}}},"required":["brew","fields","changed"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/rate_brew":{"post":{"operationId":"rate_brew","tags":["Actions: Brewing"],"summary":"Rate a brew (quick star rating)","description":"Give a brew a quick rating: 1-5 stars (half stars allowed) with an optional comment, as the evaluations tab's star rating. Example: \"rate the porter 4 stars, a bit thin\" → {brew: \"Porter\", stars: 4, comment: \"A bit thin\"}. Each call adds a rating; send evaluation_id to change an existing one. For a full BJCP or Lagerbernd scoresheet use save_scoresheet. Needs a plan with evaluations (Pro).\n\nNeeds the plan feature `bjcp_evaluations`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","feature":"bjcp_evaluations","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"stars":{"type":"number","minimum":1,"maximum":5,"multipleOf":0.5,"description":"Rating from 1 to 5 in half steps, e.g. 4 or 3.5. Required for a new rating."},"comment":{"type":"string","maxLength":2000,"description":"Tasting comment, e.g. \"Roasty, a bit thin\"."},"date":{"type":"string","format":"date","description":"Tasting date, YYYY-MM-DD. Default: today."},"evaluation_id":{"type":"string","description":"Id of the evaluation, from list_evaluations. Changes that rating instead of adding one."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"evaluation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["rating","bjcp","lagerbernd"],"description":"rating = quick star rating; bjcp / lagerbernd = scoresheet."},"by":{"type":"string","description":"\"you\" for your own, else the external evaluator's name."},"date":{"type":"string"},"stars":{"type":"number","description":"Quick rating, 1-5 stars."},"score":{"type":"number","description":"Sheet total: BJCP out of 50, Lagerbernd out of 60."},"max_score":{"type":"number"},"verdict":{"type":"string","description":"BJCP range (e.g. \"veryGood\") or Lagerbernd grade (1 best … 6)."},"submitted":{"type":"boolean","description":"false for an external evaluator's unfinished draft."},"comment":{"type":"string"}},"required":["id","kind","by"]},"created":{"type":"boolean"}},"required":["brew","evaluation","created"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_scoresheet":{"post":{"operationId":"save_scoresheet","tags":["Actions: Brewing"],"summary":"Fill in a BJCP or Lagerbernd scoresheet","description":"Start or fill in a full tasting scoresheet for a brew. BJCP (default): section scores (aroma 0-12, appearance 0-3, flavor 0-20, mouthfeel 0-5, overall 0-10; total out of 50), comments per section and off-flavors. Lagerbernd (sheet: \"lagerbernd\"): nine-step scales in ratings (total out of 60, German school grade), intensities and notes. Without evaluation_id it creates a new sheet with what you send; with evaluation_id (from list_evaluations) it updates only the fields you send. Returns the total score. For a quick star rating use rate_brew. Needs a plan with evaluations (Pro).\n\nNeeds the plan feature `bjcp_evaluations`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","feature":"bjcp_evaluations","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"sheet":{"type":"string","enum":["bjcp","lagerbernd"],"description":"Kind of a new scoresheet: \"bjcp\" (default; 50 points) or \"lagerbernd\" (60 points, nine-step scales). Ignored with evaluation_id."},"evaluation_id":{"type":"string","description":"Id of the evaluation, from list_evaluations. Updates that sheet instead of starting a new one."},"evaluator_name":{"type":"string","maxLength":80,"description":"Who tasted, e.g. \"Anna\". Default: empty (you)."},"date":{"type":"string","format":"date","description":"Tasting date, YYYY-MM-DD. Default: today for a new sheet."},"aroma_score":{"type":"integer","minimum":0,"maximum":12,"description":"BJCP aroma score, 0-12."},"appearance_score":{"type":"integer","minimum":0,"maximum":3,"description":"BJCP appearance score, 0-3."},"flavor_score":{"type":"integer","minimum":0,"maximum":20,"description":"BJCP flavor score, 0-20."},"mouthfeel_score":{"type":"integer","minimum":0,"maximum":5,"description":"BJCP mouthfeel score, 0-5."},"overall_score":{"type":"integer","minimum":0,"maximum":10,"description":"BJCP overall impression score, 0-10."},"aroma_comments":{"type":"string","maxLength":2000,"description":"BJCP aroma comments."},"appearance_comments":{"type":"string","maxLength":2000,"description":"BJCP appearance comments."},"flavor_comments":{"type":"string","maxLength":2000,"description":"BJCP flavor comments."},"mouthfeel_comments":{"type":"string","maxLength":2000,"description":"BJCP mouthfeel comments."},"overall_comments":{"type":"string","maxLength":2000,"description":"BJCP overall impression comments."},"off_flavors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Acetaldehyde","Alcoholic/Hot","Astringent","Chlorophenol","Diacetyl","DMS","Estery","Grassy","Light-struck","Medicinal","Metallic","Musty","Oxidized","Phenolic","Solvent","Sour/Acidic","Spicy","Sulfur","Vegetal","Yeasty"],"description":"Off-flavor, e.g. \"Diacetyl\"."},"intensity":{"type":"string","enum":["none","low","medium-low","medium","medium-high","high"],"description":"none, low, medium-low, medium, medium-high or high."}},"required":["name","intensity"],"additionalProperties":false},"description":"BJCP off-flavors found (replaces the list), e.g. [{\"name\": \"Diacetyl\", \"intensity\": \"low\"}]."},"ratings":{"type":"object","properties":{"color":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"clarity":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"aroma":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"body":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"carbonation":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"maltiness":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"bitterness":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"hoppiness":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"head_retention":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"head_texture":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"aromas":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"malt_character":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"hop_character":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"yeast_profile":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"balance":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"drinkability":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"off_flavors":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"bitterness_quality":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."}},"additionalProperties":false,"description":"Lagerbernd ratings, position 1-9 per scale. Fit scales (color, clarity, aroma, body, carbonation, maltiness, bitterness, hoppiness): 5 = just right, 1 too little, 9 too much. Quality (head_retention, head_texture, aromas, malt_character, hop_character, yeast_profile, balance, drinkability): 9 = best. Deductions (off_flavors, bitterness_quality): 9 = clean, 1 = severe."},"intensities":{"type":"object","properties":{"clarity":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"aroma":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"body":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"carbonation":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"maltiness":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"bitterness":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."},"hoppiness":{"anyOf":[{"type":"integer","minimum":1,"maximum":9},{"type":"null"}],"description":"Position 1-9 on the scale; null clears it."}},"additionalProperties":false,"description":"Lagerbernd descriptive intensities (not scored), 1 = low … 9 = high, per scale."},"notes":{"type":"object","properties":{"color":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Free text; null clears it."},"aromas":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Free text; null clears it."},"malt_character":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Free text; null clears it."},"hop_character":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Free text; null clears it."},"yeast_profile":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Free text; null clears it."},"off_flavors":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Free text; null clears it."},"overall":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Free text; null clears it."}},"additionalProperties":false,"description":"Lagerbernd free-text descriptors, e.g. {\"aromas\": \"bready, floral\", \"overall\": \"Clean and crisp\"}."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"evaluation":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["rating","bjcp","lagerbernd"],"description":"rating = quick star rating; bjcp / lagerbernd = scoresheet."},"by":{"type":"string","description":"\"you\" for your own, else the external evaluator's name."},"date":{"type":"string"},"stars":{"type":"number","description":"Quick rating, 1-5 stars."},"score":{"type":"number","description":"Sheet total: BJCP out of 50, Lagerbernd out of 60."},"max_score":{"type":"number"},"verdict":{"type":"string","description":"BJCP range (e.g. \"veryGood\") or Lagerbernd grade (1 best … 6)."},"submitted":{"type":"boolean","description":"false for an external evaluator's unfinished draft."},"comment":{"type":"string"}},"required":["id","kind","by"]},"created":{"type":"boolean"},"unrated_scales":{"type":"array","items":{"type":"string"},"description":"Lagerbernd scales not rated yet (they count 0)."}},"required":["brew","evaluation","created"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/list_evaluations":{"post":{"operationId":"list_evaluations","tags":["Actions: Brewing"],"summary":"List a brew's ratings and scoresheets","description":"All tastings of a brew, newest first: your quick star ratings, BJCP sheets (score out of 50) and Lagerbernd sheets (out of 60), plus sheets external evaluators submitted through the public evaluation link. Also says whether that link is on and its URL. Ids are for rate_brew / save_scoresheet (evaluation_id) and delete_evaluation.\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"include_drafts":{"type":"boolean","description":"Also list external evaluators' unsubmitted drafts (default false)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"evaluations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["rating","bjcp","lagerbernd"],"description":"rating = quick star rating; bjcp / lagerbernd = scoresheet."},"by":{"type":"string","description":"\"you\" for your own, else the external evaluator's name."},"date":{"type":"string"},"stars":{"type":"number","description":"Quick rating, 1-5 stars."},"score":{"type":"number","description":"Sheet total: BJCP out of 50, Lagerbernd out of 60."},"max_score":{"type":"number"},"verdict":{"type":"string","description":"BJCP range (e.g. \"veryGood\") or Lagerbernd grade (1 best … 6)."},"submitted":{"type":"boolean","description":"false for an external evaluator's unfinished draft."},"comment":{"type":"string"}},"required":["id","kind","by"]}},"average_stars":{"type":"number"},"public_link":{"type":"object","properties":{"enabled":{"type":"boolean"},"url":{"type":"string"}},"required":["enabled"]}},"required":["brew","evaluations","public_link"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_evaluation":{"post":{"operationId":"delete_evaluation","tags":["Actions: Brewing"],"summary":"Delete a rating or scoresheet","description":"Delete one evaluation of a brew: your star rating or scoresheet, or one an external evaluator submitted. Without confirm: true it only shows what would be deleted. Ids come from list_evaluations.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"destructive","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"evaluation_id":{"type":"string","description":"Id of the evaluation, from list_evaluations."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["evaluation_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/set_evaluation_link":{"post":{"operationId":"set_evaluation_link","tags":["Actions: Brewing"],"summary":"Turn the public evaluation link on or off","description":"The public evaluation link lets friends or judges rate a brew without an account (star rating, BJCP or Lagerbernd sheet); their sheets show up in list_evaluations. enabled: true returns the link (keeps the existing one; new_link: true replaces it so the old URL stops working). enabled: false turns it off. Turning it on needs a plan with evaluations (Pro).\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"enabled":{"type":"boolean","description":"true = link on, false = link off."},"new_link":{"type":"boolean","description":"With enabled: true, replace an existing link with a new URL."}},"required":["brew","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"batch_number":{"type":"integer"}},"required":["id","name","status"]},"enabled":{"type":"boolean"},"url":{"type":"string"}},"required":["brew","enabled"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/list_devices":{"post":{"operationId":"list_devices","tags":["Actions: Brewing"],"summary":"List fermentation devices","description":"The brewer's hydrometers and sensors (iSpindel, Tilt, RAPT Pill, GravityMon, Plaato Airlock, ...) with the brew each one logs to, its last gravity/temperature/battery and when it was last seen. Send device to see that one device's raw data log (newest first), e.g. to check whether it is sending. Gravities in SG, temperatures in °C.\n\nNeeds the plan feature `device_integrations`. Scope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"brewing","access":"read","required_scope":"brews:read","feature":"device_integrations","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"device":{"type":"string","description":"The device: its id or its exact name (e.g. \"iSpindel blue\"). Case does not matter. Omit to list all devices."},"log_limit":{"type":"integer","minimum":1,"maximum":200,"description":"With device: how many log entries (default 20)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"ispindel, tilt, tilt_bridge, rapt, hydrom, gravitymon, brewbrain, plaato_airlock or custom."},"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"],"description":"Brew it logs readings to."},"logs_keg":{"type":"boolean","description":"Attached to a keg in the cellar (scale/volume sensor)."},"gravity_offset_sg":{"type":"number","description":"Calibration added to every gravity the device sends."},"last_seen_at":{"type":"string"},"last_gravity_sg":{"type":"number"},"last_temp_c":{"type":"number"},"last_battery":{"type":"number"}},"required":["id","name","type"]}},"log":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string"},"gravity_sg":{"type":"number"},"temp_c":{"type":"number"},"battery":{"type":"number"},"angle":{"type":"number"},"pressure_psi":{"type":"number"},"bubbles_per_minute":{"type":"number"},"logged_to_brew":{"type":"boolean","description":"true when this entry became a fermentation reading of the attached brew."}},"required":["at"]},"description":"Newest data the device sent (with device)."},"log_total":{"type":"integer"}},"required":["devices"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/add_device":{"post":{"operationId":"add_device","tags":["Actions: Brewing"],"summary":"Add a fermentation device","description":"Register a hydrometer or sensor so it can send readings: returns the webhook URL to enter in the device (BrewBrain: the token) and setup_steps saying what to enter where. The URL contains the device's secret key and is shown only here, so pass it on to the brewer. Then attach the device to a brew with update_device (brew). Types: ispindel, tilt, tilt_bridge (Tilt Pi / bridge; its Tilts appear by themselves), rapt, hydrom, gravitymon, brewbrain, plaato_airlock. Custom streams are set up in the app.\n\nNeeds the plan feature `device_integrations`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","feature":"device_integrations","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["ispindel","tilt","tilt_bridge","rapt","hydrom","gravitymon","brewbrain","plaato_airlock"],"description":"Device type, e.g. \"ispindel\"."},"name":{"type":"string","minLength":1,"maxLength":80,"description":"Name to recognise it, e.g. \"iSpindel blue\"."}},"required":["type","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"ispindel, tilt, tilt_bridge, rapt, hydrom, gravitymon, brewbrain, plaato_airlock or custom."},"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"],"description":"Brew it logs readings to."},"logs_keg":{"type":"boolean","description":"Attached to a keg in the cellar (scale/volume sensor)."},"gravity_offset_sg":{"type":"number","description":"Calibration added to every gravity the device sends."},"last_seen_at":{"type":"string"},"last_gravity_sg":{"type":"number"},"last_temp_c":{"type":"number"},"last_battery":{"type":"number"}},"required":["id","name","type"]},"webhook_url":{"type":"string","description":"Enter this URL as the HTTP/webhook target in the device's settings."},"token":{"type":"string","description":"BrewBrain only: the token to enter in the BrewBrain app."},"setup_steps":{"type":"array","items":{"type":"string"},"description":"What the brewer enters where on the device, step by step (the app's connect dialog texts)."},"setup_note":{"type":"string"}},"required":["device","webhook_url","setup_steps"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_device":{"post":{"operationId":"update_device","tags":["Actions: Brewing"],"summary":"Attach a device to a brew or change its settings","description":"Attach a device to a brew so its readings are logged there (brew: the brew), detach it (brew: null), rename it, or set its gravity calibration offset (added to every gravity it sends; -0.05 to +0.05 SG). A device logs to one brew at a time; attaching it moves it (also off a keg) and moved_from names where it was. Send only what changes.\n\nNeeds the plan feature `device_integrations`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"write","required_scope":"brews:write","feature":"device_integrations","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"device":{"type":"string","description":"The device: its id or its exact name (e.g. \"iSpindel blue\"). Case does not matter."},"brew":{"type":["string","null"],"description":"Brew to log to: id, batch number (e.g. \"#12\") or exact name; null detaches the device."},"name":{"type":"string","minLength":1,"maxLength":80,"description":"New name."},"gravity_offset_sg":{"type":"number","description":"Calibration offset in SG, e.g. -0.002 when it reads 2 points high."}},"required":["device"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"ispindel, tilt, tilt_bridge, rapt, hydrom, gravitymon, brewbrain, plaato_airlock or custom."},"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"],"description":"Brew it logs readings to."},"logs_keg":{"type":"boolean","description":"Attached to a keg in the cellar (scale/volume sensor)."},"gravity_offset_sg":{"type":"number","description":"Calibration added to every gravity the device sends."},"last_seen_at":{"type":"string"},"last_gravity_sg":{"type":"number"},"last_temp_c":{"type":"number"},"last_battery":{"type":"number"}},"required":["id","name","type"]},"changed":{"type":"array","items":{"type":"string"}},"moved_from":{"type":"string","description":"Brew (or keg) the device logged to before it was attached here."}},"required":["device","changed"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_device":{"post":{"operationId":"delete_device","tags":["Actions: Brewing"],"summary":"Delete a device","description":"Remove a device and its raw data log; readings it already logged to brews stay. Its webhook URL stops working. Without confirm: true it only shows what would be deleted. To stop logging to a brew but keep the device, use update_device with brew: null.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Needs the plan feature `device_integrations`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"brewing","access":"destructive","required_scope":"brews:write","feature":"device_integrations","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"device":{"type":"string","description":"The device: its id or its exact name (e.g. \"iSpindel blue\"). Case does not matter."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["device"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_cellar":{"post":{"operationId":"get_cellar","tags":["Actions: Cellar"],"summary":"Cellar overview: what is in which vessel","description":"Shows the brewer's cellar vessels (fermenters, tanks, kegs) with what is in each today, the stays (planned or current) in a date window, and when each vessel is free. Use it for 'what's in the cellar?', 'what is free next week?' (from/to = that week; free_vessels are free all week, free_from/free_until show vessels free for part of it), or to find stay ids for save_stay / end_stay. Filter with vessel or brew. A stay is one beer in one vessel from start_date to end_date (end exclusive; no end = until ended). Volumes are in litres. Bottles/cans and keg volumes are in get_beer_stock.\n\nNeeds the plan feature `cellar`. Scope: `cellar:read` (or `read`).","x-brewforge-action":{"toolset":"cellar","access":"read","required_scope":"cellar:read","feature":"cellar","area":"cellar","idempotent":true},"security":[{"bearerAuth":["cellar:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day of the window, YYYY-MM-DD (default: today). E.g. next Monday for \"what is free next week\"."},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day of the window, YYYY-MM-DD, inclusive (default: from + 30 days)."},"vessel":{"type":"string","description":"Only this vessel: id or exact name (e.g. \"Fermenter 1\")."},"brew":{"type":"string","description":"Only stays of this brew. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"today":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"vessels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","description":"fermenter, tank, keg or other."},"capacity_l":{"type":"number"},"roles":{"type":"array","items":{"type":"string"},"description":"Roles the vessel may hold: fermenting, conditioning, serving."},"now":{"type":"object","properties":{"stay_id":{"type":"string"},"beer":{"type":"string"},"role":{"type":"string"},"until":{"type":"string","description":"Exclusive end; missing = until ended."}},"required":["stay_id","beer","role"],"description":"What is in it today; missing = empty today."},"stays":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"beer":{"type":"string"},"brew_id":{"type":"string"},"role":{"type":"string","description":"fermenting, conditioning or serving."},"name":{"type":"string"},"start_date":{"type":"string","description":"YYYY-MM-DD, first day in the vessel."},"end_date":{"type":"string","description":"YYYY-MM-DD, exclusive: the vessel is free again on this day. Missing = until ended."},"volume_l":{"type":"number","description":"Litres in the vessel (for kegs: litres left)."},"status":{"type":"string","enum":["planned","current","finished"]},"notes":{"type":"string"}},"required":["id","beer","role","start_date","status"]},"description":"Stays overlapping the from/to window, oldest first (includes the current one)."},"free_from":{"type":"string","description":"First day on/after `from` it is empty (a later day = partly free in the window). Missing = blocked by an open-ended stay (e.g. a keg on tap) until someone ends it."},"free_until":{"type":"string","description":"Exclusive: the next stay starts this day, so it is free from free_from until then. Missing = free from free_from on with nothing planned."},"free_whole_window":{"type":"boolean","description":"Empty for the whole from/to window."}},"required":["id","name","type","capacity_l","roles","stays","free_whole_window"]}},"free_vessels":{"type":"array","items":{"type":"string"},"description":"Names of vessels empty for the whole window."}},"required":["today","from","to","vessels","free_vessels"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_stay":{"post":{"operationId":"save_stay","tags":["Actions: Cellar"],"summary":"Put a beer in a vessel, or change a stay","description":"Create or change a stay (one beer in one cellar vessel for some days). Create: pass vessel and brew (or beer_name for a keg of beer that is not one of the brewer's brews), plus start_date (default today) and optionally end_date. A start_date in the future plans the stay. Change: pass stay (id, vessel name or brew) and only the fields to change; vessel moves it to another vessel. If new dates overlap later stays, nothing changes and the result has clash with would_push: show it to the user and call again with push: true to move those stays later. To fill kegs/bottles from a tank use package_beer; to empty a vessel today use end_stay. Volumes in litres; dates YYYY-MM-DD, end_date exclusive.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stay":{"type":"string","description":"Change this existing stay. Omit to create a new one. The stay: its id, or the vessel it is in (e.g. \"Fermenter 1\": the current stay there, else its only upcoming one), or the brew in it (id, batch number or exact name). Ids come from get_cellar."},"vessel":{"type":"string","description":"Vessel id or exact name, e.g. \"Fermenter 1\". Required to create; when changing, moves the stay there."},"brew":{"type":"string","description":"Create only: the beer that goes in. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"beer_name":{"type":"string","maxLength":100,"description":"Create only, instead of brew: a beer that is not one of the brewer's brews (serving kegs only), e.g. \"Guest Pils\"."},"role":{"type":"string","enum":["fermenting","conditioning","serving"],"description":"fermenting, conditioning or serving. Default: the vessel's only role, else fermenting (serving for beer_name)."},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day in the vessel, YYYY-MM-DD, e.g. \"2026-11-12\". Create default: today."},"end_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Day the vessel is free again (exclusive), YYYY-MM-DD; null = no end, until end_stay."},{"type":"null"}],"description":"Day the vessel is free again (exclusive), YYYY-MM-DD; null = no end, until end_stay."},"volume_l":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Litres in the vessel, e.g. 21.5. null = unknown."},"name":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"description":"Optional label of the stay, e.g. \"Dry hop\" (default: the role)."},"notes":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Free notes."},"push":{"type":"boolean","description":"Changing dates only: true moves the following stays later when the new dates overlap them (see clash.would_push of the previous call)."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"boolean"},"stay":{"type":"object","properties":{"id":{"type":"string"},"vessel":{"type":"string"},"vessel_id":{"type":"string"},"beer":{"type":"string"},"brew_id":{"type":"string"},"role":{"type":"string","description":"fermenting, conditioning or serving."},"name":{"type":"string"},"start_date":{"type":"string","description":"YYYY-MM-DD, first day in the vessel."},"end_date":{"type":"string","description":"YYYY-MM-DD, exclusive: the vessel is free again on this day. Missing = until ended."},"volume_l":{"type":"number","description":"Litres in the vessel (for kegs: litres left)."},"status":{"type":"string","enum":["planned","current","finished"]},"notes":{"type":"string"}},"required":["id","vessel","vessel_id","beer","role","start_date","status"]},"pushed":{"type":"array","items":{"type":"object","properties":{"stay_id":{"type":"string"},"beer":{"type":"string"},"vessel":{"type":"string"},"by_days":{"type":"number"},"new_start_date":{"type":"string"},"new_end_date":{"type":"string"}},"required":["stay_id","beer","vessel","by_days","new_start_date"]},"description":"Stays that were moved later to make room."},"clash":{"type":"object","properties":{"message":{"type":"string"},"overlaps":{"type":"array","items":{"type":"string"},"description":"Which stays would overlap."},"would_push":{"type":"array","items":{"type":"object","properties":{"stay_id":{"type":"string"},"beer":{"type":"string"},"vessel":{"type":"string"},"by_days":{"type":"number"},"new_start_date":{"type":"string"},"new_end_date":{"type":"string"}},"required":["stay_id","beer","vessel","by_days","new_start_date"]},"description":"Stays that push: true would move later, and by how many days."},"blocker":{"type":"string","description":"Why pushing cannot fix it; then change the dates or vessel instead."}},"required":["message","overlaps"],"description":"Set when nothing was saved because of overlapping stays."}},"required":["saved"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/end_stay":{"post":{"operationId":"end_stay","tags":["Actions: Cellar"],"summary":"Empty a vessel today (end a stay)","description":"Ends a current stay today, so the vessel is free from today on: the fermenter was emptied, the keg is finished. Use it for 'the keg of porter is empty' or 'I emptied Fermenter 1'. The stay stays in the history. A stay that has not started yet, or started today, cannot be ended: delete it with delete_cellar_item (kind: stay) instead. Packaging with package_beer already empties the source tank, so do not call this after packaging. Ending a keg returns an undo_token.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stay":{"type":"string","description":"The stay to end. The stay: its id, or the vessel it is in (e.g. \"Fermenter 1\": the current stay there, else its only upcoming one), or the brew in it (id, batch number or exact name). Ids come from get_cellar."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"required":["stay"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"ended":{"type":"object","properties":{"id":{"type":"string"},"vessel":{"type":"string"},"vessel_id":{"type":"string"},"beer":{"type":"string"},"brew_id":{"type":"string"},"role":{"type":"string","description":"fermenting, conditioning or serving."},"name":{"type":"string"},"start_date":{"type":"string","description":"YYYY-MM-DD, first day in the vessel."},"end_date":{"type":"string","description":"YYYY-MM-DD, exclusive: the vessel is free again on this day. Missing = until ended."},"volume_l":{"type":"number","description":"Litres in the vessel (for kegs: litres left)."},"status":{"type":"string","enum":["planned","current","finished"]},"notes":{"type":"string"}},"required":["id","vessel","vessel_id","beer","role","start_date","status"]},"undo_token":{"type":"string","description":"Pass to undo_stock_change within 15 minutes to take this change back."}},"required":["ended"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/plan_brew_cellar":{"post":{"operationId":"plan_brew_cellar","tags":["Actions: Cellar"],"summary":"Plan a brew's path through the cellar","description":"Plans where a brew will sit in the cellar, as planned stays. Without steps it builds the plan from the brew's fermentation profile, like the app's 'Plan in cellar': one step per stage (primary, cold crash, conditioning ...) back to back from start_date (default: the brew day or planned brew day), each in the best free vessel that allows its role and holds the batch. Call with dry_run: true first to show the suggestion, then again without it to save. Pass steps to choose vessels and dates yourself. Saving replaces the brew's stays that have not started yet; stays that started are kept. Dates YYYY-MM-DD, end_date exclusive. For a single stay use save_stay; to move the brew day with its plan use move_brew_day.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Profile plans only: day the first step starts, YYYY-MM-DD. Default: the brew day, else the planned brew day."},"steps":{"type":"array","items":{"type":"object","properties":{"vessel":{"type":"string","description":"Vessel id or exact name, e.g. \"Fermenter 1\"."},"role":{"type":"string","enum":["fermenting","conditioning"],"description":"fermenting or conditioning (serving kegs come from package_beer)."},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day, YYYY-MM-DD."},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Day it leaves the vessel (exclusive), YYYY-MM-DD."},"name":{"type":"string","maxLength":60,"description":"Step label, e.g. \"Primary\" or \"Cold crash\"."}},"required":["vessel","role","start_date","end_date"],"additionalProperties":false},"minItems":1,"maxItems":20,"description":"Your own plan instead of the profile's, e.g. [{\"vessel\":\"Fermenter 2\",\"role\":\"fermenting\",\"start_date\":\"2026-12-01\",\"end_date\":\"2026-12-15\",\"name\":\"Primary\"}]. Omit to plan from the fermentation profile; start_date is then ignored."},"dry_run":{"type":"boolean","description":"true = only show the plan, save nothing."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"boolean"},"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"volume_l":{"type":"number"}},"required":["id","name"]},"steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"start_date":{"type":"string"},"end_date":{"type":"string","description":"Exclusive: the next step starts this day."},"vessel":{"type":"string","description":"Missing = no vessel fits, the step is not planned."},"other_fitting_vessels":{"type":"array","items":{"type":"string"}},"why_not_planned":{"type":"string"}},"required":["name","role","start_date","end_date"]}},"replaces_planned_stays":{"type":"number","description":"How many not-yet-started stays of the brew are (or would be) replaced."},"message":{"type":"string"}},"required":["saved","brew","steps","replaces_planned_stays"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/move_brew_day":{"post":{"operationId":"move_brew_day","tags":["Actions: Cellar"],"summary":"Move a brew day and its planned cellar stays","description":"Sets a brew's planned brew day (or, once brewed, its brew day) to another date and moves the brew's planned cellar stays by the same number of days, like changing the date on the brew page. Use it for 'push the saison brew day to Saturday'. Stays that already started never move. If the moved stays would overlap other beers' stays, nothing changes and the result has clash with would_push: show it, then call again with push: true to move those later too. date null clears the date (stays keep their dates). Dates YYYY-MM-DD. Brewed on another day than planned (set_brew_status says so)? Send align_to_brew_day: true instead of date: the planned stays move so the first one starts on the actual brew day, like the brew page's 'move the cellar plan' prompt (also works when that day is today).\n\nNeeds the plan feature `cellar`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"brews:write","feature":"cellar","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"New day, YYYY-MM-DD, e.g. \"2026-11-21\"; null clears it. Not with align_to_brew_day."},{"type":"null"}],"description":"New day, YYYY-MM-DD, e.g. \"2026-11-21\"; null clears it. Not with align_to_brew_day."},"align_to_brew_day":{"type":"boolean","description":"true = keep the dates and move the brew's planned stays so the first starts on its actual brew day (after brewing on another day than planned)."},"which":{"type":"string","enum":["planned_brew_day","brew_day"],"description":"Which date to set: planned_brew_day (not brewed yet) or brew_day (the actual day). Default: brew_day if the brew has one, else planned_brew_day."},"push":{"type":"boolean","description":"true = when the moved stays overlap others, move those later too (see clash.would_push of the previous call)."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"required":["brew"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"moved":{"type":"boolean"},"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"which":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"stays_moved":{"type":"number","description":"This brew's planned stays that moved."},"stays_kept":{"type":"number","description":"Planned stays that kept their dates (date cleared)."},"pushed":{"type":"array","items":{"type":"object","properties":{"stay_id":{"type":"string"},"beer":{"type":"string"},"vessel":{"type":"string"},"by_days":{"type":"number"},"new_start_date":{"type":"string"},"new_end_date":{"type":"string"}},"required":["stay_id","beer","vessel","by_days","new_start_date"]},"description":"Other beers' stays moved later to make room."},"clash":{"type":"object","properties":{"message":{"type":"string"},"overlaps":{"type":"array","items":{"type":"string"},"description":"Which stays would overlap."},"would_push":{"type":"array","items":{"type":"object","properties":{"stay_id":{"type":"string"},"beer":{"type":"string"},"vessel":{"type":"string"},"by_days":{"type":"number"},"new_start_date":{"type":"string"},"new_end_date":{"type":"string"}},"required":["stay_id","beer","vessel","by_days","new_start_date"]},"description":"Stays that push: true would move later, and by how many days."},"blocker":{"type":"string","description":"Why pushing cannot fix it; then change the dates or vessel instead."}},"required":["message","overlaps"],"description":"Set when nothing changed because of overlapping stays."}},"required":["moved","brew","which"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_cellar_vessel":{"post":{"operationId":"save_cellar_vessel","tags":["Actions: Cellar"],"summary":"Add or edit a vessel or bottle/can container","description":"Sets up the cellar. kind \"vessel\" = one named fermenter, tank or keg (e.g. \"Fermenter 1\", \"Corny 3\"); stays put beer in it. kind \"container\" = a pool of identical bottles, cans or small kegs counted by number (e.g. \"0.5 L bottles\", 48 owned). Omit ref to create; pass ref (id or exact name) to change only the fields you pass. Volumes in litres. Returns the saved item and, for a container, how many are filled and empty. Delete with delete_cellar_item.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["vessel","container"],"description":"\"vessel\" (fermenter/tank/keg, one at a time) or \"container\" (bottles/cans counted)."},"ref":{"type":"string","description":"Change this existing vessel/container: id or exact name. Omit to create a new one."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name, e.g. \"Fermenter 2\" or \"0.33 L cans\". Required to create."},"type":{"type":"string","enum":["fermenter","tank","keg","other","bottle","can"],"description":"Vessel: fermenter, tank, keg or other (default fermenter). Container: bottle, can, keg or other (default bottle)."},"volume_l":{"type":"number","exclusiveMinimum":0,"description":"Capacity in litres, e.g. 30 for a fermenter, 0.5 for a bottle. Required to create."},"roles":{"type":"array","items":{"type":"string","enum":["fermenting","conditioning","serving"]},"minItems":1,"description":"Vessel only: what it may hold, e.g. [\"fermenting\",\"conditioning\"]. Default by type: keg → serving, tank → conditioning, else both."},"quantity_owned":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Container only: how many you own (empty + filled), e.g. 48. null = not tracked."},"serial_number":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Vessel only: serial or keg number."},"tare_weight_kg":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Vessel only: empty weight in kg (for keg scales)."},"color":{"anyOf":[{"type":"string","enum":["slate","red","orange","amber","yellow","lime","green","teal","cyan","blue","indigo","violet","purple","pink"]},{"type":"null"}],"description":"Vessel only: colour tag, e.g. amber, blue, green."},"notes":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Free notes."}},"required":["kind"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"},"vessel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"capacity_l":{"type":"number"},"roles":{"type":"array","items":{"type":"string"}}},"required":["id","name","type","capacity_l","roles"]},"container":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"volume_l":{"type":"number"},"quantity_owned":{"type":"number"},"filled":{"type":"number"},"empty":{"type":"number","description":"Owned minus filled; negative = more filled than owned."}},"required":["id","name","type","volume_l","filled"]}},"required":["created"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_cellar_item":{"post":{"operationId":"delete_cellar_item","tags":["Actions: Cellar"],"summary":"Delete a stay, vessel or container","description":"Deletes a stay (removes it from the cellar history entirely, e.g. a wrong or no longer wanted planned stay), a vessel, or a bottle/can container. To record that a vessel was emptied today, use end_stay instead (keeps the history). Vessels with current or planned stays and containers with stock cannot be deleted; the error says what to clear first. Without confirm: true it only shows what would be deleted.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Needs the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"destructive","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["stay","vessel","container"],"description":"stay = one beer's time in a vessel (e.g. a planned stay made by mistake); vessel = a fermenter/tank/keg; container = a bottle/can pool."},"ref":{"type":"string","description":"What to delete. Stay: The stay: its id, or the vessel it is in (e.g. \"Fermenter 1\": the current stay there, else its only upcoming one), or the brew in it (id, batch number or exact name). Ids come from get_cellar. Vessel or container: its id or exact name (e.g. \"Corny 3\", \"0.33 L cans\")."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["kind","ref"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_packaging_context":{"post":{"operationId":"get_packaging_context","tags":["Actions: Cellar"],"summary":"Before packaging: volume, free kegs, bottles","description":"Call before package_beer. Shows where the beer comes from and how many litres are there (available_l; estimate: true means it is the recipe's estimate), which kegs are free to fill (only free kegs can be used), and the bottle/can containers with how many empties are available. Pass brew (e.g. the brew's name) or from_vessel (e.g. a keg to move into bottles). Volumes in litres.\n\nNeeds the plan feature `cellar`. Scope: `cellar:read` (or `read`).","x-brewforge-action":{"toolset":"cellar","access":"read","required_scope":"cellar:read","feature":"cellar","area":"cellar","idempotent":true},"security":[{"bearerAuth":["cellar:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"Package this brew (from the tank it is in, or straight from the brew if it is in no vessel). The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"from_vessel":{"type":"string","description":"Instead of brew: the vessel (or stay id) the beer comes out of, e.g. \"Brite tank\" or a keg \"Corny 2\" to move beer from a keg into bottles."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"today":{"type":"string"},"source":{"type":"object","properties":{"beer":{"type":"string"},"brew_id":{"type":"string"},"from":{"type":"string","description":"The vessel the beer comes out of, or the brew itself (\"brew\") when it is in no vessel."},"available_l":{"type":"number","description":"Litres to package from."},"estimate":{"type":"boolean","description":"available_l is the recipe's estimate, not a measured tank volume: pass available_l to package_beer if the brewer knows better."},"is_keg":{"type":"boolean","description":"Repackaging from a keg: the keg stays until end_stay, even at 0 L."}},"required":["beer","from","available_l","estimate","is_keg"]},"kegs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"capacity_l":{"type":"number"},"free":{"type":"boolean"},"reason":{"type":"string","description":"Why it cannot be used now."}},"required":["name","capacity_l","free"]}},"containers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"volume_l":{"type":"number","description":"Litres per bottle/can."},"empty_available":{"type":"number","description":"Empty ones on hand (missing = not counted; negative = short)."},"already_in_stock":{"type":"number","description":"How many of this beer are already in stock in it."}},"required":["name","type","volume_l"]}}},"required":["today","source","kegs","containers"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/package_beer":{"post":{"operationId":"package_beer","tags":["Actions: Cellar"],"summary":"Package beer into kegs, bottles or cans","description":"Records packaging day: beer from a brew (its tank, or straight from the brew) or from a vessel goes into kegs (litres each) and bottles/cans (counts), with loss in litres. Example: 'kegged the pale ale today: 19 L into Corny 1, 6 bottles of 0.5 L, half a litre lost' → {\"brew\":\"Pale Ale\",\"kegs\":[{\"keg\":\"Corny 1\",\"volume_l\":19}],\"containers\":[{\"container\":\"0.5 L bottles\",\"count\":6}],\"loss_l\":0.5}. Call get_packaging_context first to see the litres available, the free kegs and the container names. Each keg becomes a serving stay holding its litres; bottles/cans add to stock; the source tank is emptied (source_empty) and the brew gets its packaging date. If packaged litres plus loss do not match what is available it still packages, and warnings says so (tell the user; pass available_l when the tank held more than shown). An overfilled keg is refused.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"string","description":"Package this brew (from the tank it is in, or straight from the brew if it is in no vessel). The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"from_vessel":{"type":"string","description":"Instead of brew: the vessel (or stay id) the beer comes out of, e.g. \"Brite tank\" or a keg \"Corny 2\" to move beer from a keg into bottles."},"kegs":{"type":"array","items":{"type":"object","properties":{"keg":{"type":"string","description":"Keg id or exact name, e.g. \"Corny 1\". Must be free (see get_packaging_context)."},"volume_l":{"type":"number","exclusiveMinimum":0,"description":"Litres filled into this keg, e.g. 19."}},"required":["keg","volume_l"],"additionalProperties":false},"maxItems":50,"description":"Kegs filled; each keg once."},"containers":{"type":"array","items":{"type":"object","properties":{"container":{"type":"string","description":"Bottle/can container id or exact name, e.g. \"0.5 L bottles\"."},"count":{"type":"integer","exclusiveMinimum":0,"description":"How many were filled, e.g. 24."}},"required":["container","count"],"additionalProperties":false},"maxItems":50,"description":"Bottles/cans filled, by container type."},"loss_l":{"type":"number","minimum":0,"description":"Litres lost (trub, spills, left in lines), e.g. 0.5. Default 0."},"available_l":{"type":"number","minimum":0,"description":"Litres actually in the source, when get_packaging_context showed estimate: true or no volume. Ignored when the tank has a measured volume."},"source_empty":{"type":"boolean","description":"true = the source is empty afterwards (tank stay ends). Default: true for a tank or brew, false when repackaging from a keg (kegs are ended with end_stay)."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"packaged":{"type":"boolean"},"beer":{"type":"string"},"changes":{"type":"array","items":{"type":"string"},"description":"What changed, in words."},"source_free_from":{"type":"string","description":"Day the emptied tank is free (YYYY-MM-DD)."},"warnings":{"type":"array","items":{"type":"string"},"description":"Packaged litres + loss above or below what was available; tell the user."}},"required":["packaged","beer","changes"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_beer_stock":{"post":{"operationId":"get_beer_stock","tags":["Actions: Cellar"],"summary":"Beer on hand: kegs, bottles and cans","description":"Lists the packaged beer the brewer has: kegs on tap or ready (litres left, keg sensor), bottle/can stock lines (beer × container, count), and the containers with how many are owned, filled and empty. Use for 'how much porter is left?' or before update_keg / update_bottle_stock. Filter with beer (part of a beer name). Volumes in litres. Beer still in fermenters/tanks is in get_cellar.\n\nNeeds the plan feature `cellar`. Scope: `cellar:read` (or `read`).","x-brewforge-action":{"toolset":"cellar","access":"read","required_scope":"cellar:read","feature":"cellar","area":"cellar","idempotent":true},"security":[{"bearerAuth":["cellar:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"beer":{"type":"string","description":"Only beers whose name contains this text, e.g. \"porter\"."},"include_empty":{"type":"boolean","description":"Also list stock lines at 0 (default false)."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"kegs":{"type":"array","items":{"type":"object","properties":{"stay_id":{"type":"string","description":"Use as keg in update_keg (the keg name works too)."},"keg":{"type":"string"},"beer":{"type":"string"},"brew_id":{"type":"string"},"volume_l":{"type":"number","description":"Litres left; missing = never entered."},"capacity_l":{"type":"number"},"pints_left":{"type":"number","description":"0.5 L pours left."},"since":{"type":"string"},"sensor":{"type":"string","description":"Name of the attached keg sensor that owns the volume."}},"required":["stay_id","keg","beer","capacity_l","since"]}},"bottles_and_cans":{"type":"array","items":{"type":"object","properties":{"line_id":{"type":"string"},"beer":{"type":"string"},"brew_id":{"type":"string"},"container":{"type":"string"},"count":{"type":"number"},"volume_l":{"type":"number","description":"count × container volume."}},"required":["line_id","beer","container","count","volume_l"]}},"containers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"volume_l":{"type":"number"},"owned":{"type":"number"},"filled":{"type":"number"},"empty":{"type":"number","description":"Negative = more filled than owned."}},"required":["name","type","volume_l","filled"]}},"keg_sensors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"attached_to_keg":{"type":"boolean"}},"required":["id","name","attached_to_keg"]},"description":"Devices that can measure a keg (update_keg action attach_sensor)."}},"required":["kegs","bottles_and_cans","containers","keg_sensors"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_keg":{"post":{"operationId":"update_keg","tags":["Actions: Cellar"],"summary":"Update a keg: litres left, pour, empty, sensor","description":"Changes a keg that is on tap or ready (a current serving stay). action: set_volume = the real litres left (volume_l); pour = take litres out (pour_l, default 0.5; it lowers the litres left now: pours have no date or history, so an earlier pour is simply recorded now); free = the keg is empty and free from today; link_brew = a keg of a hand-typed beer belongs to one of the brewer's brews (brew); attach_sensor / detach_sensor = a keg scale or volume sensor (device) takes over / stops measuring the volume. Kegs with a sensor attached cannot be set by hand. Returns the keg and an undo_token (undo_stock_change). Filling kegs is package_beer; list kegs with get_beer_stock.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keg":{"type":"string","description":"The keg: its name (e.g. \"Corny 2\"), the beer in it (brew name or batch number), or stay_id from get_beer_stock."},"action":{"type":"string","enum":["set_volume","pour","free","link_brew","attach_sensor","detach_sensor"],"description":"What to do: set_volume, pour, free, link_brew, attach_sensor or detach_sensor."},"volume_l":{"type":"number","minimum":0,"description":"set_volume: litres left now, e.g. 12.5."},"pour_l":{"type":"number","exclusiveMinimum":0,"description":"pour: litres poured, e.g. 0.5 for a pint (default 0.5). Recorded now; pours cannot be backdated."},"brew":{"type":"string","description":"link_brew: the brew this beer is. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"device":{"type":"string","description":"attach_sensor / detach_sensor: device id or exact name, e.g. \"Keg scale 1\" (see get_beer_stock keg_sensors)."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"required":["keg","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"keg":{"type":"object","properties":{"id":{"type":"string"},"vessel":{"type":"string"},"vessel_id":{"type":"string"},"beer":{"type":"string"},"brew_id":{"type":"string"},"role":{"type":"string","description":"fermenting, conditioning or serving."},"name":{"type":"string"},"start_date":{"type":"string","description":"YYYY-MM-DD, first day in the vessel."},"end_date":{"type":"string","description":"YYYY-MM-DD, exclusive: the vessel is free again on this day. Missing = until ended."},"volume_l":{"type":"number","description":"Litres in the vessel (for kegs: litres left)."},"status":{"type":"string","enum":["planned","current","finished"]},"notes":{"type":"string"},"pints_left":{"type":"number"}},"required":["id","vessel","vessel_id","beer","role","start_date","status"]},"undo_token":{"type":"string","description":"Pass to undo_stock_change within 15 minutes to take this change back."}},"required":["keg"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_bottle_stock":{"post":{"operationId":"update_bottle_stock","tags":["Actions: Cellar"],"summary":"Change bottle/can stock","description":"Changes the count of bottles or cans of a beer. action: adjust = add/remove some (delta, e.g. -3 after drinking three); set_count = the real count after counting (count); add = add stock by hand, e.g. bought cans or beer not packaged in BrewForge (container, beer, count; creates the line if needed); gone = bottles that left for good (given away, broken, one-way): lowers how many of the container are owned (container, count) — use adjust first to take them out of stock; link_brew = stock of a hand-typed beer belongs to one of the brewer's brews (beer = the typed name, brew). Point at stock with beer (brew name, batch number or typed name) and container (when the beer is in several), or line_id from get_beer_stock. Returns an undo_token.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["add","adjust","set_count","gone","link_brew"],"description":"add, adjust, set_count, gone or link_brew."},"beer":{"type":"string","description":"The beer: brew id, batch number, brew name or a hand-typed beer name, e.g. \"Oatmeal Stout\". For add: a brew, else it is stored as a typed name."},"container":{"type":"string","description":"Bottle/can container id or exact name, e.g. \"0.5 L bottles\". Required for add and gone."},"line_id":{"type":"string","description":"Instead of beer + container: the line_id from get_beer_stock."},"count":{"type":"integer","minimum":0,"description":"set_count: the new count; add / gone: how many, e.g. 12."},"delta":{"type":"integer","description":"adjust: change, e.g. -2 or 6 (between -1000 and 1000, not 0)."},"brew":{"type":"string","description":"link_brew: the brew (id, batch number or exact name)."}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"beer":{"type":"string"},"container":{"type":"string"},"count":{"type":"number","description":"Bottles/cans of this beer in this container now."},"container_owned":{"type":"number","description":"How many of the container are owned now."},"container_empty":{"type":"number"},"undo_token":{"type":"string","description":"Pass to undo_stock_change within 15 minutes to take this change back."}},"required":["container"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/undo_stock_change":{"post":{"operationId":"undo_stock_change","tags":["Actions: Cellar"],"summary":"Undo a keg or bottle stock change","description":"Takes back one change made by update_keg, update_bottle_stock or end_stay on a keg, using the undo_token that call returned (valid 15 minutes). It only undoes while nothing else changed that keg or stock line since; otherwise it says so and changes nothing.\n\nNeeds the plan feature `cellar`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"cellar","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"undo_token":{"type":"string","minLength":10,"description":"The undo_token returned by the change, exactly as given."},"today":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The brewer's local date today, YYYY-MM-DD (e.g. \"2026-11-11\"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia)."}},"required":["undo_token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"undone":{"type":"boolean"}},"required":["undone"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_taplist":{"post":{"operationId":"get_taplist","tags":["Actions: Cellar"],"summary":"Tap lists: beers, taps, menus and screens","description":"Shows the brewer's tap lists (the beers on offer in a taproom, at home or at an event). With one list (or list given): its beers, its taps with what is pouring and next up, the menus/screens showing it with their public URLs, guest add-links, and brews that could still be added. With several lists and no list: a summary of each list plus the menu and screen designs. Call it before manage_tap or save_taplist_beer to see names and ids.\n\nNeeds the plan feature `taplist`. Scope: `cellar:read` (or `read`).","x-brewforge-action":{"toolset":"cellar","access":"read","required_scope":"cellar:read","feature":"taplist","area":"cellar","idempotent":true},"security":[{"bearerAuth":["cellar:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"string","description":"The tap list: its id or exact name (e.g. \"Taproom\"). Optional when the brewer has only one tap list."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"lists":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"beers":{"type":"number"},"taps":{"type":"number"},"menus":{"type":"array","items":{"type":"string"}},"screens":{"type":"array","items":{"type":"string"}}},"required":["id","name","beers","taps","menus","screens"]},"description":"All lists (when no single list is shown)."},"list":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"default_serving":{"type":"string"},"auto_add_completed":{"type":"boolean","description":"Completed brews are added automatically."},"include_conditioning":{"type":"boolean"},"beers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brew_id":{"type":"string"},"style":{"type":"string"},"abv_pct":{"type":"number","description":"% ABV."},"ibu":{"type":"number"},"color_ebc":{"type":"number","description":"Colour in EBC."},"color_srm":{"type":"number","description":"Colour in SRM (what tap lists store)."},"serving":{"type":"array","items":{"type":"string"},"description":"tap, bottle, can, growler."},"available":{"type":"boolean","description":"false = hidden from menus and screens."},"on_tap":{"type":"string","description":"Tap it is on now."},"next_up_on":{"type":"string","description":"Tap it comes on next."}},"required":["id","name","serving","available"]}},"taps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"pouring":{"type":"string","description":"Beer on this tap now."},"next_up":{"type":"string","description":"Beer that comes on next (promote with manage_tap)."}},"required":["id","name","enabled"]}},"menus":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"pdf_url":{"type":"string","description":"PDF download, valid 15 minutes."}},"required":["id","name","url","pdf_url"]},"description":"Printable menus showing this list: url is the public page, pdf_url a print-ready PDF."},"screens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"}},"required":["id","name","url","active"]},"description":"TV screens showing this list."},"guest_links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"added":{"type":"number"},"max":{"type":"number"},"expiry_date":{"type":"string"}},"required":["id","url","active","added"]}},"brews_to_add":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"]},"description":"Brews not on the list yet that fit it."}},"required":["id","name","default_serving","auto_add_completed","include_conditioning","beers","taps","menus","screens","guest_links","brews_to_add"]},"designs":{"type":"object","properties":{"menus":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"template":{"type":"string"},"lists":{"type":"array","items":{"type":"string"}}},"required":["id","name","template","lists"]}},"screens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"template":{"type":"string"},"lists":{"type":"array","items":{"type":"string"}}},"required":["id","name","template","lists"]}},"templates":{"type":"object","properties":{"menu":{"type":"array","items":{"type":"string"}},"screen":{"type":"array","items":{"type":"string"}}},"required":["menu","screen"],"description":"Template ids for manage_taplist_sharing create."}},"required":["menus","screens","templates"]}}}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_tap_list":{"post":{"operationId":"save_tap_list","tags":["Actions: Cellar"],"summary":"Create or edit a tap list","description":"Creates a tap list (the beers on offer somewhere: a taproom, the home bar, an event) or changes its settings. Omit list to create (name required); pass list (id or exact name) to change only the fields given. taps: n creates n taps with the list. Then add beers with save_taplist_beer, put them on taps with manage_tap, and share it with manage_taplist_sharing (a menu or screen link guests open to see the list).\n\nNeeds the plan feature `taplist`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"taplist","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"string","description":"Change this existing tap list (id or exact name). Omit to create a new one."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name, e.g. \"Home bar\". Required to create."},"description":{"type":"string","maxLength":500,"description":"Short text shown under the title on menus and screens."},"default_serving":{"type":"string","enum":["tap","bottle","can","growler"],"description":"How new beers are served by default: tap, bottle, can or growler (default tap)."},"auto_add_completed":{"type":"boolean","description":"true = brews that reach completed are added automatically."},"include_conditioning":{"type":"boolean","description":"true = also offer brews still conditioning when adding."},"taps":{"type":"integer","minimum":1,"maximum":40,"description":"Create: also create this many taps, named \"Tap 1\", \"Tap 2\", ... (e.g. 4). Add more later with manage_tap action create."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"},"list":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"default_serving":{"type":"string"},"auto_add_completed":{"type":"boolean"},"include_conditioning":{"type":"boolean"}},"required":["id","name","default_serving","auto_add_completed","include_conditioning"]},"taps":{"type":"array","items":{"type":"string"},"description":"Names of the list's taps."}},"required":["created","list"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_taplist_beer":{"post":{"operationId":"save_taplist_beer","tags":["Actions: Cellar"],"summary":"Add a beer to a tap list, or change it","description":"Adds a beer to a tap list or changes how it is shown. beer = one of the brewer's brews (name, batch number or id): added if it is not on the list yet, otherwise changed; its style, ABV, IBU come from the brew. name without beer = add a beer that is not one of the brewer's brews (a guest beer), with style/abv_pct/... typed in. beer + name = show it under another name. Override fields (style, abv_pct, ...) replace the brew's values on menus; null clears an override. available: false hides it without removing it; position moves it in the list (1 = first). Putting it on a tap is manage_tap; removing it is delete_taplist_item.\n\nNeeds the plan feature `taplist`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"taplist","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"string","description":"The tap list: its id or exact name (e.g. \"Taproom\"). Optional when the brewer has only one tap list."},"beer":{"type":"string","description":"A beer on the list (id or shown name) or a brew to add (id, batch number or exact name), e.g. \"Oatmeal Stout\"."},"name":{"type":"string","maxLength":200,"description":"Shown name. Without beer: adds a guest beer of this name, e.g. \"Augustiner Helles\"."},"brewer":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Brewer shown, e.g. a guest brewery."},"style":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Style shown, e.g. \"Helles\"."},"abv_pct":{"anyOf":[{"type":"number","minimum":0,"maximum":30},{"type":"null"}],"description":"% ABV shown, e.g. 5.2."},"ibu":{"anyOf":[{"type":"number","minimum":0,"maximum":200},{"type":"null"}],"description":"IBU shown."},"og_sg":{"anyOf":[{"type":"number","minimum":0.99,"maximum":1.2},{"type":"null"}],"description":"Original gravity (SG, e.g. 1.048)."},"fg_sg":{"anyOf":[{"type":"number","minimum":0.99,"maximum":1.1},{"type":"null"}],"description":"Final gravity (SG, e.g. 1.010)."},"color_ebc":{"anyOf":[{"type":"number","minimum":0,"maximum":200},{"type":"null"}],"description":"Colour in EBC, e.g. 8. Send this or color_srm."},"color_srm":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}],"description":"Colour in SRM, e.g. 4 (tap lists store SRM). Send this or color_ebc."},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"Tasting notes shown on menus."},"serving":{"type":"array","items":{"type":"string","enum":["tap","bottle","can","growler"]},"minItems":1,"maxItems":4,"description":"How it is served, e.g. [\"tap\"] or [\"bottle\",\"can\"]. Only \"tap\" beers can go on a tap."},"available":{"type":"boolean","description":"false hides it from menus/screens (e.g. sold out); true shows it again."},"position":{"type":"integer","minimum":1,"description":"Place in the list, 1 = first."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"boolean"},"list":{"type":"string"},"beer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brew_id":{"type":"string"},"style":{"type":"string"},"abv_pct":{"type":"number","description":"% ABV."},"ibu":{"type":"number"},"color_ebc":{"type":"number","description":"Colour in EBC."},"color_srm":{"type":"number","description":"Colour in SRM (what tap lists store)."},"serving":{"type":"array","items":{"type":"string"},"description":"tap, bottle, can, growler."},"available":{"type":"boolean","description":"false = hidden from menus and screens."},"on_tap":{"type":"string","description":"Tap it is on now."},"next_up_on":{"type":"string","description":"Tap it comes on next."}},"required":["id","name","serving","available"]}},"required":["added","list","beer"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/manage_tap":{"post":{"operationId":"manage_tap","tags":["Actions: Cellar"],"summary":"Taps: put a beer on, next up, add/rename taps","description":"Works with the taps of a tap list. action: put_on = the beer pours from this tap now; next_up = the beer comes on this tap next; promote = the next-up beer goes on now (keg changed); clear = nothing pours from the tap; clear_next_up; create = new tap (name); rename (name); enable / disable; move (position, 1 = first). Example: \"put the porter on tap 2 and make the saison next up\" = two calls: {\"tap\":\"Tap 2\",\"action\":\"put_on\",\"beer\":\"Porter\"} then {\"tap\":\"Tap 2\",\"action\":\"next_up\",\"beer\":\"Saison\"}. beer is a beer on the list or a brew (added to the list automatically). tap is the tap's name or id (\"2\" finds \"Tap 2\"). Returns all taps of the list.\n\nNeeds the plan feature `taplist`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"taplist","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"string","description":"The tap list: its id or exact name (e.g. \"Taproom\"). Optional when the brewer has only one tap list."},"action":{"type":"string","enum":["put_on","next_up","promote","clear","clear_next_up","create","rename","enable","disable","move"],"description":"put_on, next_up, promote, clear, clear_next_up, create, rename, enable, disable or move."},"tap":{"type":"string","description":"The tap: name or id, e.g. \"Tap 2\". Not needed for create."},"beer":{"type":"string","description":"put_on / next_up: the beer (name on the list, or a brew name / batch number), e.g. \"Porter\"."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"create / rename: the tap name, e.g. \"Tap 3\" or \"Nitro\"."},"position":{"type":"integer","minimum":1,"description":"move: new place, 1 = first."}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"list":{"type":"string"},"tap":{"type":"string","description":"The tap that changed."},"added_to_list":{"type":"string","description":"Set when the beer was not on the list yet and was added to it (served on tap) first: its name on the list."},"taps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"pouring":{"type":"string","description":"Beer on this tap now."},"next_up":{"type":"string","description":"Beer that comes on next (promote with manage_tap)."}},"required":["id","name","enabled"]}}},"required":["list","taps"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/manage_taplist_sharing":{"post":{"operationId":"manage_taplist_sharing","tags":["Actions: Cellar"],"summary":"Menus, TV screens and guest links of tap lists","description":"Two different kinds of link. (1) A link guests OPEN TO SEE the list: kind menu (an online menu page, also printable as PDF) or kind screen (a TV display page); 'share my tap list' / 'a page guests can look at' = menu (create with list). (2) kind guest_link = a link where guests ADD THEIR OWN beers to the list (e.g. a bottle share); it does not show the list. Menus/screens are designs that can be shown on several lists, each with its own public URL. actions: create (name, template, optional list to show it on right away, title; screen: show taps/bottles/both), update (design: name/title/show), show_on (design + list), remove_from (design + list), activate / deactivate (screen on a list); guest_link: create (list, max_entries, expires_in_days) or revoke. Templates: menu classic, modern, brewery, taphouse-board, minimal; screen taproom, modern, chalkboard, taphouse-board. Colours, fonts and layout are edited in the app's design editor (not here). Returns the public URLs; menus also a PDF link to print.\n\nNeeds the plan feature `taplist`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"taplist","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["menu","screen","guest_link"],"description":"menu = page guests open to see the list (and PDF); screen = TV page showing the list; guest_link = page where guests add beers to the list."},"action":{"type":"string","enum":["create","update","show_on","remove_from","activate","deactivate","revoke"],"description":"create, update, show_on, remove_from, activate, deactivate (screens), revoke (guest links)."},"design":{"type":"string","description":"The menu or screen: id or exact name (not for create)."},"list":{"type":"string","description":"The tap list: its id or exact name (e.g. \"Taproom\"). Optional when the brewer has only one tap list."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"create / update: design name, e.g. \"Bar TV\"."},"template":{"type":"string","description":"create: template id (menu: classic, modern, brewery, taphouse-board, minimal; screen: taproom, modern, chalkboard, taphouse-board). Default: the first."},"title":{"type":"string","maxLength":200,"description":"Heading shown on the menu/screen (default: the list name)."},"show":{"type":"string","enum":["taps","bottles","both"],"description":"Screens: which beers to show (default both)."},"link":{"type":"string","description":"revoke: the guest link id or URL (optional when the list has one active link)."},"max_entries":{"type":"integer","minimum":1,"maximum":1000,"description":"Guest link create: how many beers guests may add in total."},"expires_in_days":{"type":"integer","minimum":1,"maximum":365,"description":"Guest link create: days until the link stops working."}},"required":["kind","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"template":{"type":"string"},"url":{"type":"string","description":"guest_link: the URL where guests add beers (it does not show the list)."},"list":{"type":"string"},"shown_on":{"type":"array","items":{"type":"object","properties":{"list":{"type":"string"},"url":{"type":"string"},"pdf_url":{"type":"string","description":"Menus: PDF download, valid 15 minutes."},"active":{"type":"boolean"}},"required":["list","url","active"]},"description":"Lists the design is shown on, with public URLs (menus also a print-ready PDF link)."},"message":{"type":"string"}},"required":["kind","id"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_taplist_item":{"post":{"operationId":"delete_taplist_item","tags":["Actions: Cellar"],"summary":"Delete a tap list, beer, tap, menu or screen","description":"Removes something from the tap lists: a whole list (with its beers, taps, guest add-links and the list's public menu/screen links; the menu/screen designs themselves stay), a beer from a list (it also leaves its tap), a tap, or a menu/screen design (its public URLs stop working). To hide a sold-out beer without removing it, use save_taplist_beer with available: false; to take a beer off a tap, manage_tap action clear. Without confirm: true it only shows what would be deleted.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Needs the plan feature `taplist`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"destructive","required_scope":"cellar:write","feature":"taplist","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["list","beer","tap","menu","screen"],"description":"list = a whole tap list; beer = a beer on a list; tap = a tap of a list; menu / screen = a design (taken off every list)."},"ref":{"type":"string","description":"What to delete: its id or name (a beer also by its brew name), e.g. \"Tap 4\" or \"Guest Pils\". For kind list: the list."},"list":{"type":"string","description":"For beer and tap: the list it is on. The tap list: its id or exact name (e.g. \"Taproom\"). Optional when the brewer has only one tap list."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["kind","ref"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_labels":{"post":{"operationId":"get_labels","tags":["Actions: Cellar"],"summary":"Label templates and the label text of brews","description":"Bottle/cap label templates and what they print. No input: the templates (name, size in mm, shape). template: that template's elements (text with {{placeholders}}, positions in mm). brew: the values the placeholders print for that brew (name, style, abv, ibu, og, fg, batch, brewer, brew_date, packaging_date), formatted in the brewer's units and language. Printing happens in the app (Labels page); this tool reads and save_label_template edits.\n\nNeeds the plan feature `labels`. Scope: `cellar:read` (or `read`).","x-brewforge-action":{"toolset":"cellar","access":"read","required_scope":"cellar:read","feature":"labels","area":"cellar","idempotent":true},"security":[{"bearerAuth":["cellar:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"string","description":"A template id or exact name, e.g. \"Cap 19 mm\", to get its elements."},"brew":{"type":"string","description":"Get the label values for this brew. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"width_mm":{"type":"number"},"height_mm":{"type":"number"},"shape":{"type":"string"}},"required":["id","name","width_mm","height_mm","shape"]}},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"width_mm":{"type":"number"},"height_mm":{"type":"number"},"shape":{"type":"string"},"elements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image"],"description":"\"text\" (default) or \"image\" (the brewer's logo; at most one)."},"id":{"type":"string","minLength":1,"maxLength":64,"description":"Unique per label, e.g. \"1\"."},"content":{"type":"string","maxLength":500,"description":"Text: words and placeholders, e.g. \"{{name}} · {{abv}}% ABV\". Placeholders: {{name}}, {{style}}, {{abv}}, {{ibu}}, {{og}}, {{fg}}, {{batch}}, {{brewer}}, {{brew_date}}, {{packaging_date}}; they print the value only (abv \"5.2\", no % sign: write \"{{abv}}% ABV\")."},"x":{"type":"number","minimum":0,"maximum":100,"description":"mm from the left edge. Text: the point it aligns to, so with align center x = width/2 centres it (e.g. 13 on a 26 mm cap)."},"y":{"type":"number","minimum":0,"maximum":100,"description":"mm from the top edge."},"font_family":{"type":"string","description":"Text: one of Inter, DM Sans, Source Serif 4, Playfair Display, JetBrains Mono, Caveat (default Inter)."},"font_size_pt":{"type":"number","minimum":4,"maximum":48,"description":"Text: points, e.g. 8 (default 8)."},"bold":{"type":"boolean","description":"Text: bold (default false)."},"align":{"type":"string","enum":["left","center","right"],"description":"Text: alignment around x (default center)."},"width_mm":{"type":"number","minimum":1,"description":"Image: width in mm."},"height_mm":{"type":"number","minimum":1,"description":"Image: height in mm."}},"required":["id","x","y"]}}},"required":["id","name","width_mm","height_mm","shape","elements"]},"brew_values":{"type":"object","additionalProperties":{"type":"string"},"description":"Placeholder → printed text for the brew."},"placeholders":{"type":"array","items":{"type":"string"}},"fonts":{"type":"array","items":{"type":"string"}}},"required":["templates","placeholders","fonts"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_label_template":{"post":{"operationId":"save_label_template","tags":["Actions: Cellar"],"summary":"Create, edit or copy a label template","description":"Creates or changes a bottle/cap label template. Omit template to create (name; size default 19×19 mm round with the beer name and style). Pass template (id or name) to change only the given fields; elements replaces all elements. duplicate: true copies the template (name = the copy's name). Sizes in mm (5-100); text elements use placeholders like {{name}} that print each brew's values (see get_labels).\n\nNeeds the plan feature `labels`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"labels","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"string","description":"Change (or with duplicate, copy) this template: id or exact name. Omit to create."},"duplicate":{"type":"boolean","description":"true = copy template instead of changing it."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name, e.g. \"Crown cap 26 mm\". Required to create."},"width_mm":{"type":"number","minimum":5,"maximum":100,"description":"Label width in mm, e.g. 26."},"height_mm":{"type":"number","minimum":5,"maximum":100,"description":"Label height in mm."},"shape":{"type":"string","enum":["round","rectangle"],"description":"round (caps) or rectangle."},"elements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image"],"description":"\"text\" (default) or \"image\" (the brewer's logo; at most one)."},"id":{"type":"string","minLength":1,"maxLength":64,"description":"Unique per label, e.g. \"1\"."},"content":{"type":"string","maxLength":500,"description":"Text: words and placeholders, e.g. \"{{name}} · {{abv}}% ABV\". Placeholders: {{name}}, {{style}}, {{abv}}, {{ibu}}, {{og}}, {{fg}}, {{batch}}, {{brewer}}, {{brew_date}}, {{packaging_date}}; they print the value only (abv \"5.2\", no % sign: write \"{{abv}}% ABV\")."},"x":{"type":"number","minimum":0,"maximum":100,"description":"mm from the left edge. Text: the point it aligns to, so with align center x = width/2 centres it (e.g. 13 on a 26 mm cap)."},"y":{"type":"number","minimum":0,"maximum":100,"description":"mm from the top edge."},"font_family":{"type":"string","description":"Text: one of Inter, DM Sans, Source Serif 4, Playfair Display, JetBrains Mono, Caveat (default Inter)."},"font_size_pt":{"type":"number","minimum":4,"maximum":48,"description":"Text: points, e.g. 8 (default 8)."},"bold":{"type":"boolean","description":"Text: bold (default false)."},"align":{"type":"string","enum":["left","center","right"],"description":"Text: alignment around x (default center)."},"width_mm":{"type":"number","minimum":1,"description":"Image: width in mm."},"height_mm":{"type":"number","minimum":1,"description":"Image: height in mm."}},"required":["id","x","y"],"additionalProperties":false},"maxItems":50,"description":"All elements of the label, e.g. [{\"id\":\"1\",\"content\":\"{{name}}\",\"x\":13,\"y\":10,\"font_size_pt\":9,\"bold\":true}]."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"width_mm":{"type":"number"},"height_mm":{"type":"number"},"shape":{"type":"string"},"elements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image"],"description":"\"text\" (default) or \"image\" (the brewer's logo; at most one)."},"id":{"type":"string","minLength":1,"maxLength":64,"description":"Unique per label, e.g. \"1\"."},"content":{"type":"string","maxLength":500,"description":"Text: words and placeholders, e.g. \"{{name}} · {{abv}}% ABV\". Placeholders: {{name}}, {{style}}, {{abv}}, {{ibu}}, {{og}}, {{fg}}, {{batch}}, {{brewer}}, {{brew_date}}, {{packaging_date}}; they print the value only (abv \"5.2\", no % sign: write \"{{abv}}% ABV\")."},"x":{"type":"number","minimum":0,"maximum":100,"description":"mm from the left edge. Text: the point it aligns to, so with align center x = width/2 centres it (e.g. 13 on a 26 mm cap)."},"y":{"type":"number","minimum":0,"maximum":100,"description":"mm from the top edge."},"font_family":{"type":"string","description":"Text: one of Inter, DM Sans, Source Serif 4, Playfair Display, JetBrains Mono, Caveat (default Inter)."},"font_size_pt":{"type":"number","minimum":4,"maximum":48,"description":"Text: points, e.g. 8 (default 8)."},"bold":{"type":"boolean","description":"Text: bold (default false)."},"align":{"type":"string","enum":["left","center","right"],"description":"Text: alignment around x (default center)."},"width_mm":{"type":"number","minimum":1,"description":"Image: width in mm."},"height_mm":{"type":"number","minimum":1,"description":"Image: height in mm."}},"required":["id","x","y"]}}},"required":["id","name","width_mm","height_mm","shape","elements"]}},"required":["created","template"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_label_template":{"post":{"operationId":"delete_label_template","tags":["Actions: Cellar"],"summary":"Delete a label template","description":"Deletes a label template (printed labels are not affected). Without confirm: true it only shows which template would be deleted.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Needs the plan feature `labels`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"destructive","required_scope":"cellar:write","feature":"labels","area":"cellar","idempotent":false},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"string","description":"Template id or exact name."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["template"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/set_trmnl_screen":{"post":{"operationId":"set_trmnl_screen","tags":["Actions: Cellar"],"summary":"Choose what a TRMNL e-ink screen shows","description":"Sets what a connected TRMNL e-ink display shows: show fermentation (one fermenting brew's gravity and temperature; brew) or stock (beer on hand; stock_display text or icons). Call without show/brew/stock_display to list the connected screens and their settings. Connecting a TRMNL device happens on trmnl.com, not here.\n\nNeeds the plan feature `trmnl`. Scope: `cellar:write` (or `write`).","x-brewforge-action":{"toolset":"cellar","access":"write","required_scope":"cellar:write","feature":"trmnl","area":"cellar","idempotent":true},"security":[{"bearerAuth":["cellar:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"screen":{"type":"string","description":"The TRMNL screen: id or name. Optional when only one is connected."},"show":{"type":"string","enum":["fermentation","stock"],"description":"fermentation or stock."},"brew":{"type":"string","description":"Fermentation screen: the fermenting brew to show. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"stock_display":{"type":"string","enum":["text","icons"],"description":"Stock screen: amounts as text (litres, counts) or icons."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"screens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"show":{"type":"string"},"brew":{"type":"string"},"stock_display":{"type":"string"},"last_shown":{"type":"string"}},"required":["id","name","show","stock_display"]}},"changed":{"type":"string","description":"Name of the screen that was changed."}},"required":["screens"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/find_stock":{"post":{"operationId":"find_stock","tags":["Actions: Inventory"],"summary":"Find ingredient stock","description":"List the user's ingredient stock (the inventory: malts, hops, yeasts, misc) with amounts, lots, expiry dates, suppliers and prices. Filter by name, type or status (used up, expiring within 90 days, expired, or low: below max_amount). Amounts: grams for fermentables and hops, the row's own unit for yeast (pkg, ml, g, cells) and misc. Costs are in the user's currency (see get_started). Each row id works as stock in update_stock (change amounts, \"I used 50 g of Citra\") and remove_stock. To see which ingredients exist (not what is in stock), use find_ingredients. summary gives per type how many rows are in stock / used up and the total weight in grams.\n\nScope: `inventory:read` (or `read`).","x-brewforge-action":{"toolset":"inventory","access":"read","required_scope":"inventory:read","area":"inventory","idempotent":true},"security":[{"bearerAuth":["inventory:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Text the ingredient name contains (e.g. \"citra\", \"pils\")."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"status":{"type":"string","enum":["in_stock","used_up","expiring_soon","expired","low"],"description":"Only rows in this state: \"in_stock\" (amount > 0), \"used_up\" (amount 0, kept for restocking), \"expiring_soon\" (within 90 days), \"expired\", \"low\" (in stock but at most max_amount). Default: all rows."},"max_amount":{"type":"number","minimum":0,"description":"With status \"low\" (or alone): only rows with at most this amount in their unit, e.g. 100 (grams for hops/malts, packs for yeast)."},"limit":{"type":"integer","minimum":1,"maximum":200,"description":"How many rows to return, 1-200 (default 50)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stock row id (pass as stock to update_stock / remove_stock)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string"},"amount":{"type":"number","description":"Amount in stock, in unit."},"unit":{"type":"string","description":"\"g\" for fermentables and hops; the row's own unit for yeast (pkg, ml, g, cells) and misc (g, ml, each, mg)."},"status":{"type":"string","enum":["in_stock","used_up","expiring_soon","expired"],"description":"used_up: amount 0; expiring_soon: expires within 90 days."},"lot":{"type":"string"},"expiry_date":{"type":"string"},"purchase_date":{"type":"string"},"supplier":{"type":"string"},"cost_per_kg":{"type":"number","description":"Fermentables/hops, user's currency."},"cost_per_unit":{"type":"number","description":"Yeast/misc, per unit, user's currency."},"alpha_acid_pct":{"type":"number"},"form":{"type":"string"},"harvest_year":{"type":"integer"},"lab":{"type":"string"},"notes":{"type":"string"}},"required":["id","type","name","ingredient_id","amount","unit","status"]}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."},"summary":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"in_stock":{"type":"integer"},"used_up":{"type":"integer"},"total_g":{"type":"number","description":"Total weight in stock in grams (only when every row of the type is weighed in grams)."}},"required":["type","in_stock","used_up"]},"description":"Totals per type over all the user's stock (ignores the filters)."}},"required":["items","next_cursor","summary"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/add_stock":{"post":{"operationId":"add_stock","tags":["Actions: Inventory"],"summary":"Add ingredient stock","description":"Book bought ingredients into the inventory, e.g. \"5 kg Pilsner malt\" or \"100 g Citra 2025 pellets at 13.2% alpha\". One call per ingredient. The ingredient is referenced by id or exact name and must be in the user's ingredient picker (find_ingredients lists them; a missing one can be picked from a package with select_package_ingredients or created with save_custom_ingredient). type is inferred from the ingredient; pass it only to narrow an ambiguous name. Amount: fermentables/hops in g (default), kg, oz or lb, stored as grams; yeast in pkg (default), ml, g or cells; misc in the ingredient's unit. If a row of the same ingredient and lot (for hops also form, alpha and harvest year) exists, the amount is added to it and the price becomes the weighted average (merged_into_existing: true). The result has the recorded price with currency. Everything else is optional: lot, expiry date, supplier, price, notes; hops: alpha_acid_pct, form, harvest_year; yeast: manufacturing_date.\n\nScope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ingredient":{"type":"string","description":"The ingredient: its id (from find_ingredients) or its exact name (e.g. \"Citra\", \"Pilsner Malt\", \"SafAle US-05\"; yeast also by product code like \"US-05\"). Case does not matter; when several picked packages have the name, the one in stock (then the user's own) is used. Only ingredients in the user's ingredient picker (My Ingredients plus the ingredients chosen from packages) can be used."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"amount":{"type":"number","exclusiveMinimum":0,"description":"How much was bought, in unit (e.g. 5 with unit \"kg\", 100 for 100 g, 2 packs of yeast)."},"unit":{"type":"string","enum":["g","kg","oz","lb","mg","pkg","ml","cells","each"],"description":"Unit of amount. Fermentables and hops are stored in grams: send \"g\" (default), \"kg\", \"oz\" or \"lb\". Yeast counts in \"pkg\" (packs, default), \"ml\", \"g\" or \"cells\"; misc in \"g\", \"ml\", \"each\" or \"mg\" (default: the ingredient's own unit)."},"lot":{"type":"string","maxLength":100,"description":"Lot or batch number on the bag (e.g. \"L2025-118\")."},"expiry_date":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"Best before / expiry date, YYYY-MM-DD (e.g. \"2027-03-31\"); YYYY-MM means the last day of that month."},"purchase_date":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"When it was bought, YYYY-MM-DD (e.g. \"2026-11-11\"); YYYY-MM means the last day of that month."},"supplier":{"type":"string","maxLength":200,"description":"Where it was bought (e.g. \"Hopfen der Welt\")."},"cost_per_kg":{"type":"number","minimum":0,"description":"Price per kg, for fermentables and hops, in the user's currency (e.g. 2.4)."},"cost_per_unit":{"type":"number","minimum":0,"description":"Price per counted unit (per pack for yeast in pkg, per gram for misc in g, ...), in the user's currency (e.g. 4.5)."},"total_cost":{"type":"number","minimum":0,"description":"What the whole amount cost, in the user's currency (e.g. 12.9 for 5 kg); converted to the price per kg or per unit. Use instead of cost_per_kg / cost_per_unit."},"notes":{"type":"string","maxLength":500,"description":"Free text."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Hops only: alpha acid % of this lot (e.g. 13.2); default is the catalog value."},"form":{"type":"string","enum":["pellet","whole","cryo","extract"],"description":"Hops only: \"pellet\" (default), \"whole\", \"cryo\" or \"extract\"."},"harvest_year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Hops only: crop year (e.g. 2025)."},"manufacturing_date":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"Yeast only: production date, YYYY-MM-DD (e.g. \"2027-03-31\"); YYYY-MM means the last day of that month."}},"required":["ingredient","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"stock":{"type":"object","properties":{"id":{"type":"string","description":"Stock row id (pass as stock to update_stock / remove_stock)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string"},"amount":{"type":"number","description":"Amount in stock, in unit."},"unit":{"type":"string","description":"\"g\" for fermentables and hops; the row's own unit for yeast (pkg, ml, g, cells) and misc (g, ml, each, mg)."},"status":{"type":"string","enum":["in_stock","used_up","expiring_soon","expired"],"description":"used_up: amount 0; expiring_soon: expires within 90 days."},"lot":{"type":"string"},"expiry_date":{"type":"string"},"purchase_date":{"type":"string"},"supplier":{"type":"string"},"cost_per_kg":{"type":"number","description":"Fermentables/hops, user's currency."},"cost_per_unit":{"type":"number","description":"Yeast/misc, per unit, user's currency."},"alpha_acid_pct":{"type":"number"},"form":{"type":"string"},"harvest_year":{"type":"integer"},"lab":{"type":"string"},"notes":{"type":"string"}},"required":["id","type","name","ingredient_id","amount","unit","status"]},"merged_into_existing":{"type":"boolean","description":"true: the amount was added to an existing row of the same ingredient and lot (no new row); stock shows the row's new total and weighted-average price."},"added":{"type":"object","properties":{"amount":{"type":"number"},"unit":{"type":"string"}},"required":["amount","unit"],"description":"What this call added, in the row's unit."},"price":{"type":"object","properties":{"cost_per_kg":{"type":"number"},"cost_per_unit":{"type":"number"},"per":{"type":"string","description":"What cost_per_unit is per, e.g. \"pkg\" or \"g\"."},"currency":{"type":"string","description":"The user's currency (Settings), e.g. EUR."}},"required":["currency"],"description":"The price now recorded on the row (after a merge: the weighted average), with currency. Absent when no price is known."}},"required":["stock","merged_into_existing","added"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_stock":{"post":{"operationId":"update_stock","tags":["Actions: Inventory"],"summary":"Use up, correct or edit stock","description":"Change one stock row: take an amount out (\"I used 50 g of Citra\" → change: -50), add to it (change: 500), set the counted amount (amount: 1200), or edit its lot, expiry date, supplier, price, notes, or hop alpha/form/harvest year. Reference the row by id (from find_stock) or ingredient name; if a name has several rows and only one still has stock, a negative change uses that one. change and amount use the row's unit (grams for fermentables/hops; send unit \"kg\"/\"oz\"/\"lb\" to convert). Stock never goes below 0. To book a new purchase use add_stock (it merges lots); deducting a whole brew's ingredients belongs to the brew tools. Text fields: send \"\" to clear.\n\nScope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stock":{"type":"string","description":"The stock row: its id (from find_stock) or the ingredient's exact name (e.g. \"Citra\"). A name that matches several rows (lots, harvest years) returns them as candidates; call again with the row id."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"change":{"type":"number","description":"Add (positive) or take out (negative) this much, e.g. -50 for \"used 50 g\"."},"amount":{"type":"number","minimum":0,"description":"Set the amount in stock to this (after counting), e.g. 1200. Use instead of change."},"unit":{"type":"string","enum":["g","kg","oz","lb","mg","pkg","ml","cells","each"],"description":"Unit of amount. Fermentables and hops are stored in grams: send \"g\" (default), \"kg\", \"oz\" or \"lb\". Yeast counts in \"pkg\" (packs, default), \"ml\", \"g\" or \"cells\"; misc in \"g\", \"ml\", \"each\" or \"mg\" (default: the ingredient's own unit)."},"lot":{"type":"string","maxLength":100,"description":"Lot number."},"expiry_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"Expiry date, YYYY-MM-DD (e.g. \"2027-03-31\"); YYYY-MM means the last day of that month."},{"type":"string","const":""}],"description":"Expiry date, YYYY-MM-DD (e.g. \"2027-03-31\"); YYYY-MM means the last day of that month."},"supplier":{"type":"string","maxLength":200,"description":"Where it was bought."},"cost_per_kg":{"type":"number","minimum":0,"description":"Price per kg, for fermentables and hops, in the user's currency (e.g. 2.4)."},"cost_per_unit":{"type":"number","minimum":0,"description":"Price per counted unit (per pack for yeast in pkg, per gram for misc in g, ...), in the user's currency (e.g. 4.5)."},"total_cost":{"type":"number","minimum":0,"description":"What the whole amount cost, in the user's currency (e.g. 12.9 for 5 kg); converted to the price per kg or per unit. Use instead of cost_per_kg / cost_per_unit."},"notes":{"type":"string","maxLength":500,"description":"Free text."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Hops only: alpha acid % of this lot."},"form":{"type":"string","enum":["pellet","whole","cryo","extract"],"description":"Hops only: pellet, whole, cryo or extract."},"harvest_year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Hops only: crop year."},"manufacturing_date":{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"Yeast only: production date, YYYY-MM-DD (e.g. \"2027-03-31\"); YYYY-MM means the last day of that month."}},"required":["stock"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"stock":{"type":"object","properties":{"id":{"type":"string","description":"Stock row id (pass as stock to update_stock / remove_stock)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string"},"amount":{"type":"number","description":"Amount in stock, in unit."},"unit":{"type":"string","description":"\"g\" for fermentables and hops; the row's own unit for yeast (pkg, ml, g, cells) and misc (g, ml, each, mg)."},"status":{"type":"string","enum":["in_stock","used_up","expiring_soon","expired"],"description":"used_up: amount 0; expiring_soon: expires within 90 days."},"lot":{"type":"string"},"expiry_date":{"type":"string"},"purchase_date":{"type":"string"},"supplier":{"type":"string"},"cost_per_kg":{"type":"number","description":"Fermentables/hops, user's currency."},"cost_per_unit":{"type":"number","description":"Yeast/misc, per unit, user's currency."},"alpha_acid_pct":{"type":"number"},"form":{"type":"string"},"harvest_year":{"type":"integer"},"lab":{"type":"string"},"notes":{"type":"string"}},"required":["id","type","name","ingredient_id","amount","unit","status"]},"previous_amount":{"type":"number","description":"Amount before this call, in the row's unit."},"note":{"type":"string"}},"required":["stock","previous_amount"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/remove_stock":{"post":{"operationId":"remove_stock","tags":["Actions: Inventory"],"summary":"Remove a stock row","description":"Delete one stock row from the inventory (e.g. a wrong entry or an old lot that is thrown away). Without confirm: true it only shows the row that would be removed. To record that an amount was used, use update_stock with a negative change instead: a used-up row (amount 0) stays so it can be restocked. The ingredient itself stays in the picker and in recipes.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"destructive","required_scope":"inventory:write","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stock":{"type":"string","description":"The stock row: its id (from find_stock) or the ingredient's exact name (e.g. \"Citra\"). A name that matches several rows (lots, harvest years) returns them as candidates; call again with the row id."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["stock"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/find_ingredients":{"post":{"operationId":"find_ingredients","tags":["Actions: Inventory"],"summary":"Find ingredients","description":"Search the ingredient catalog by name and type, with key specs (color, alpha acid, attenuation, ...). Use it to find the exact name or id that add_stock, order items and recipe tools expect. scope \"picker\" (default) lists what the user can use right now: My Ingredients plus the ingredients chosen from packages. scope \"catalog\" searches every package BrewForge offers (query required), including ingredients not picked yet (in_picker: false); pick those with select_package_ingredients. This lists ingredients, not stock; find_stock shows amounts in stock.\n\nScope: `inventory:read` (or `read`).","x-brewforge-action":{"toolset":"inventory","access":"read","required_scope":"inventory:read","area":"inventory","idempotent":true},"security":[{"bearerAuth":["inventory:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Text the name contains, e.g. \"citra\", \"pilsner\", \"us-05\". Required for scope \"catalog\" (at least 2 characters)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"scope":{"type":"string","enum":["picker","catalog"],"description":"\"picker\" (default): ingredients the user can use. \"catalog\": search all packages, including ones not in the picker."},"own_only":{"type":"boolean","description":"Only the user's own ingredients (My Ingredients and imported ones)."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 25)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Ingredient id: works as ingredient in add_stock, order items and recipes."},"name":{"type":"string"},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"package":{"type":"string","description":"Package it comes from (\"My Ingredients\" for the user's own)."},"package_id":{"type":"string"},"own":{"type":"boolean","description":"true for the user's own ingredients (can be edited/deleted with save_custom_ingredient / delete_custom_ingredient)."},"in_picker":{"type":"boolean","description":"true when it can be used in recipes and stock; false: pick it first with select_package_ingredients."}},"required":["id","name","type","package","package_id","in_picker"],"additionalProperties":{},"description":"Plus key specs by type: fermentable kind, color_ebc, potential_ppg, origin, maltster; hop alpha_acid_pct, purpose, origin, harvest_year; yeast lab, product_id, kind, form, attenuation_pct, temp_min_c, temp_max_c; misc kind, default_unit."}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."},"hint":{"type":"string","description":"Set when the picker has no match but other packages do."}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_custom_ingredient":{"post":{"operationId":"save_custom_ingredient","tags":["Actions: Inventory"],"summary":"Create or edit an own ingredient","description":"Create an ingredient in My Ingredients (when the catalog does not have it), or edit one of the user's own ingredients. Create: leave out ingredient, send type and name plus any specs. Edit: send ingredient (id or name of an own ingredient; find_ingredients with own_only: true lists them) and only the fields to change; the type comes from the ingredient. Catalog ingredients from packages cannot be edited. Ingredients from an import (e.g. a Brewfather import package) can be moved into My Ingredients with move_to_my_ingredients: true (merges with a matching entry there). Fields by type: fermentable kind, color_ebc, potential_ppg, origin, maltster, non_fermentable, max_usage_pct; hop alpha_acid_pct, beta_acid_pct, purpose, origin, harvest_year, aroma; yeast lab, product_id, kind, form, attenuation_min_pct, attenuation_max_pct, temp_min_c, temp_max_c, flocculation, alcohol_tolerance_pct; misc kind, default_unit. All: description. Send \"\" to clear a text field.\n\nScope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ingredient":{"type":"string","description":"Edit this own ingredient (id or exact name, e.g. \"Homegrown Cascade\"). Leave out to create a new one."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Required to create: fermentable, hop, yeast or misc."},"name":{"type":"string","maxLength":200,"description":"Name (required to create), e.g. \"Homegrown Cascade\"."},"kind":{"type":"string","description":"Sub-type. Fermentable: grain, sugar, extract, dry_extract, adjunct, fruit (default grain). Yeast: ale, lager, wheat, wine, champagne, brett, kveik. Misc: water_agent, fining, flavor, spice, herb, fruit, nutrient, other."},"color_ebc":{"type":"number","minimum":0,"maximum":4000,"description":"Fermentable color in EBC (e.g. 3.5 for Pilsner malt)."},"potential_ppg":{"type":"number","minimum":0,"maximum":50,"description":"Fermentable extract potential in PPG (e.g. 37)."},"origin":{"type":"string","maxLength":100,"description":"Country of origin (e.g. \"Germany\")."},"maltster":{"type":"string","maxLength":200,"description":"Fermentable maltster/brand."},"non_fermentable":{"type":"boolean","description":"Fermentable that yeast cannot ferment (lactose, maltodextrin)."},"max_usage_pct":{"type":"number","minimum":0,"maximum":100,"description":"Fermentable: max share in the grist, %."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Hop alpha acid % (e.g. 7.5)."},"beta_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Hop beta acid %."},"purpose":{"type":"string","enum":["bittering","aroma","dual"],"description":"Hop purpose: bittering, aroma or dual."},"harvest_year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Hop harvest (crop) year, e.g. 2025."},"aroma":{"type":"string","maxLength":1000,"description":"Hop aroma profile."},"lab":{"type":"string","maxLength":100,"description":"Yeast lab (e.g. \"Fermentis\")."},"product_id":{"type":"string","maxLength":50,"description":"Yeast product code (e.g. \"US-05\")."},"form":{"type":"string","enum":["dry","liquid"],"description":"Yeast form: dry or liquid."},"attenuation_min_pct":{"type":"number","minimum":0,"maximum":100,"description":"Yeast attenuation, low end %."},"attenuation_max_pct":{"type":"number","minimum":0,"maximum":100,"description":"Yeast attenuation, high end %."},"temp_min_c":{"type":"number","minimum":-5,"maximum":50,"description":"Yeast lowest fermentation temperature, °C."},"temp_max_c":{"type":"number","minimum":-5,"maximum":50,"description":"Yeast highest fermentation temperature, °C."},"flocculation":{"type":"string","enum":["low","medium","high","very_high"],"description":"Yeast flocculation."},"alcohol_tolerance_pct":{"type":"number","minimum":0,"maximum":25,"description":"Yeast alcohol tolerance, % ABV."},"default_unit":{"type":"string","enum":["g","mg","ml","tsp","tbsp","each"],"description":"Misc: unit it is usually dosed and stocked in."},"description":{"type":"string","maxLength":2000,"description":"Free text."},"move_to_my_ingredients":{"type":"boolean","description":"Edit only: move an imported ingredient (from an import package) into My Ingredients. Stock, recipes and orders stay linked."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"ingredient":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"package":{"type":"string"}},"required":["id","name","type","package"],"additionalProperties":{}},"created":{"type":"boolean"},"moved":{"type":"string","enum":["moved","merged"],"description":"merged: an entry with the same source already existed in My Ingredients and the import was folded into it."}},"required":["ingredient","created"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_custom_ingredient":{"post":{"operationId":"delete_custom_ingredient","tags":["Actions: Inventory"],"summary":"Delete an own ingredient","description":"Delete one of the user's own ingredients (My Ingredients or an imported one). Without confirm: true it only shows what is affected: its stock rows (deleted with it) and the brews whose recipes use it (they keep the ingredient's name and amounts but lose the link). Catalog ingredients from packages cannot be deleted; to hide one from the picker, use select_package_ingredients with remove.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"destructive","required_scope":"inventory:write","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ingredient":{"type":"string","description":"The own ingredient: its id or exact name (e.g. \"Homegrown Cascade\")."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["ingredient"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_ingredient_packages":{"post":{"operationId":"get_ingredient_packages","tags":["Actions: Inventory"],"summary":"List or open ingredient packages","description":"Ingredient packages are the catalog: collections of malts, hops, yeasts and misc from one supplier (e.g. \"Weyermann\"), plus the user's own packages (My Ingredients, imports). Only picked ingredients show in the user's picker for recipes and stock. Without package: lists every package with ingredient counts and how much of it is picked (in_picker all/some/none). With package (id or name): that package's ingredients with key specs and in_picker per ingredient, filterable by type and name. To find which package has an ingredient use find_ingredients with scope \"catalog\". To pick ingredients use select_package_ingredients.\n\nScope: `inventory:read` (or `read`).","x-brewforge-action":{"toolset":"inventory","access":"read","required_scope":"inventory:read","area":"inventory","idempotent":true},"security":[{"bearerAuth":["inventory:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"package":{"type":"string","description":"The ingredient package: its id or exact name (e.g. \"Weyermann\", \"Yakima Chief Hops\"). get_ingredient_packages lists them. Leave out to list all packages."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Only packages / ingredients of this type."},"query":{"type":"string","description":"Text in the package name (list) or ingredient name (one package)."},"limit":{"type":"integer","minimum":1,"maximum":200,"description":"How many rows to return, 1-200 (default 50)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["catalog","own","myIngredients"],"description":"catalog: offered by BrewForge; own / myIngredients: the user's own packages (always fully in the picker)."},"supplier":{"type":"string"},"region":{"type":"string"},"ingredients":{"type":"object","properties":{"fermentable":{"type":"integer"},"hop":{"type":"integer"},"yeast":{"type":"integer"},"misc":{"type":"integer"}},"required":["fermentable","hop","yeast","misc"]},"in_picker":{"type":"string","enum":["all","some","none"],"description":"How many of its ingredients are in the user's picker."}},"required":["id","name","kind","ingredients","in_picker"]}},"package":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["catalog","own","myIngredients"],"description":"catalog: offered by BrewForge; own / myIngredients: the user's own packages (always fully in the picker)."},"supplier":{"type":"string"},"region":{"type":"string"},"ingredients":{"type":"object","properties":{"fermentable":{"type":"integer"},"hop":{"type":"integer"},"yeast":{"type":"integer"},"misc":{"type":"integer"}},"required":["fermentable","hop","yeast","misc"]},"in_picker":{"type":"string","enum":["all","some","none"],"description":"How many of its ingredients are in the user's picker."},"description":{"type":"string"},"website":{"type":"string"}},"required":["id","name","kind","ingredients","in_picker"]},"ingredients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"in_picker":{"type":"boolean"}},"required":["id","name","type","in_picker"],"additionalProperties":{}}},"next_cursor":{"type":["string","null"]}},"required":["next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/select_package_ingredients":{"post":{"operationId":"select_package_ingredients","tags":["Actions: Inventory"],"summary":"Pick ingredients from a package","description":"Choose which ingredients of a catalog package show in the user's ingredient picker (and so can be used in recipes, stock and orders). select: \"all\" adds the whole package (ingredients the supplier adds later included); select: \"none\" removes all of it; add / remove change single ingredients (ids or exact names within that package, from get_ingredient_packages or find_ingredients; when several packages offer the same ingredient, pick by id). Removing only hides ingredients from the picker: recipes and stock keep their copies. The user's own packages (My Ingredients, imports) are always fully picked.\n\nScope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","area":"inventory","idempotent":true},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"package":{"type":"string","description":"The ingredient package: its id or exact name (e.g. \"Weyermann\", \"Yakima Chief Hops\"). get_ingredient_packages lists them."},"select":{"type":"string","enum":["all","none"],"description":"\"all\": the whole package; \"none\": nothing from it. Can be combined with add/remove, which apply after it."},"add":{"type":"array","items":{"type":"string"},"maxItems":200,"description":"Ingredients of this package to add to the picker: ids or exact names, e.g. [\"Citra\", \"Mosaic\"]."},"remove":{"type":"array","items":{"type":"string"},"maxItems":200,"description":"Ingredients of this package to take out of the picker: ids or exact names."}},"required":["package"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"package":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"selected":{"type":"integer","description":"Ingredients of the package now in the picker."},"total":{"type":"integer"},"whole_package":{"type":"boolean","description":"true when the whole package is picked, including later additions."},"added":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"description":"Ingredients passed in add."},"removed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"description":"Ingredients passed in remove."}},"required":["package","selected","total","whole_package"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_orders":{"post":{"operationId":"get_orders","tags":["Actions: Inventory"],"summary":"List orders or open one","description":"Orders are the user's purchasing lists (what to buy from a shop, what is on the way, what arrived). Without order: lists orders, newest activity first, with status, item and arrival counts and costs; filter by status or name. With order (id or name): that order with all its lines (line ids, amounts, units, received, prices) and next_step. Costs are in the user's currency. Line ids are what edit_order_items and receive_order take.\n\nNeeds the plan feature `orders`. Scope: `inventory:read` (or `read`).","x-brewforge-action":{"toolset":"inventory","access":"read","required_scope":"inventory:read","feature":"orders","area":"inventory","idempotent":true},"security":[{"bearerAuth":["inventory:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"string","description":"The order: its id (from get_orders) or its exact name (e.g. \"Hopfen der Welt November\"). Case does not matter. Leave out to list orders."},"status":{"type":"array","items":{"type":"string","enum":["draft","ordered","partial","received"]},"description":"List only orders in these statuses, e.g. [\"ordered\", \"partial\"] for what is on the way."},"query":{"type":"string","description":"Text in the order name or supplier."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 20)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"supplier":{"type":"string"},"status":{"type":"string","enum":["draft","ordered","partial","received"]},"ordered_date":{"type":"string"},"expected_date":{"type":"string"},"received_date":{"type":"string"},"shipping_cost":{"type":"number"},"notes":{"type":"string"},"item_count":{"type":"integer"},"arrived_count":{"type":"integer"},"items_cost":{"type":"number","description":"Sum of the line prices that are set, user's currency."},"total_cost":{"type":"number","description":"items_cost plus shipping."},"next_step":{"type":"string","enum":["add_items","mark_ordered","receive","mark_received"],"description":"What to do next: add_items (edit_order_items), mark_ordered (save_order status \"ordered\"), receive (receive_order), mark_received (save_order status \"received\")."},"free_text_items":{"type":"array","items":{"type":"string"},"description":"Lines without a linked ingredient: they are skipped when booking into stock."}},"required":["id","name","status","item_count","arrived_count"]}},"order":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"supplier":{"type":"string"},"status":{"type":"string","enum":["draft","ordered","partial","received"]},"ordered_date":{"type":"string"},"expected_date":{"type":"string"},"received_date":{"type":"string"},"shipping_cost":{"type":"number"},"notes":{"type":"string"},"item_count":{"type":"integer"},"arrived_count":{"type":"integer"},"items_cost":{"type":"number","description":"Sum of the line prices that are set, user's currency."},"total_cost":{"type":"number","description":"items_cost plus shipping."},"next_step":{"type":"string","enum":["add_items","mark_ordered","receive","mark_received"],"description":"What to do next: add_items (edit_order_items), mark_ordered (save_order status \"ordered\"), receive (receive_order), mark_received (save_order status \"received\")."},"free_text_items":{"type":"array","items":{"type":"string"},"description":"Lines without a linked ingredient: they are skipped when booking into stock."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Order line id (item in edit_order_items / receive_order)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string","description":"Missing for free-text lines; those cannot be booked into stock."},"form":{"type":"string"},"alpha_acid_pct":{"type":"number"},"harvest_year":{"type":"integer"},"amount":{"type":"number","description":"Amount needed/requested, in unit."},"ordered_amount":{"type":"number","description":"Amount actually ordered, when it differs from amount."},"unit":{"type":"string"},"received":{"type":"number"},"remaining":{"type":"number","description":"Still to arrive."},"arrival":{"type":"string","enum":["pending","partial","arrived"]},"estimated_cost":{"type":"number"},"price_paid":{"type":"number","description":"Price for the whole line."},"notes":{"type":"string"}},"required":["id","type","name","amount","unit","received","remaining","arrival"]}}},"required":["id","name","status","item_count","arrived_count","items"]},"next_cursor":{"type":["string","null"]}},"required":["next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_order":{"post":{"operationId":"save_order","tags":["Actions: Inventory"],"summary":"Create or edit an order","description":"Create an order (a purchasing list for one shop) or change one: name, supplier, status, shipping cost, expected delivery date, notes. Create: leave out order and send name (plus optional items to put on it right away). Edit: send order (id or name) and only what changes. Status: \"draft\" (still to order), \"ordered\" (placed; its items count as on order in the planner), \"partial\" (some items arrived), \"received\" (everything arrived). Setting \"ordered\" stamps the order date. Setting \"received\" does NOT book anything into stock: to put arrived items into the inventory use receive_order. To add, change or remove lines later use edit_order_items. To build an order from what the planned brews are short of, use create_order_from_shortages.\n\nNeeds the plan feature `orders`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","feature":"orders","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"string","description":"The order: its id (from get_orders) or its exact name (e.g. \"Hopfen der Welt November\"). Case does not matter. Leave out to create a new order."},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Order name (required to create), e.g. \"Hopfen der Welt November\"."},"supplier":{"type":"string","maxLength":200,"description":"Shop or supplier (e.g. \"Hopfen der Welt\"); \"\" clears it. Becomes the stock rows' supplier when receiving."},"status":{"type":"string","enum":["draft","ordered","partial","received"],"description":"\"draft\" (still to order), \"ordered\" (placed; its items count as on order in the planner), \"partial\" (some items arrived), \"received\" (everything arrived). New orders start as \"draft\"."},"shipping_cost":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Shipping for the whole order in the user's currency (split over the line prices when receiving); null clears it."},"expected_date":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$","description":"Expected delivery date, YYYY-MM-DD (e.g. \"2026-11-20\"); YYYY-MM means the last day of that month."},{"type":"string","const":""}],"description":"Expected delivery date, YYYY-MM-DD (e.g. \"2026-11-20\"); YYYY-MM means the last day of that month."},"notes":{"type":"string","maxLength":1000,"description":"Free text; \"\" clears it."},"items":{"type":"array","items":{"type":"object","properties":{"ingredient":{"type":"string","description":"Ingredient id or exact name from the user's picker (e.g. \"Citra\"). An ingredient that is not in the picker can still be ordered as a free-text line: pass its name and type (it is then not linked, so it cannot be booked into stock until linked)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount to buy, in unit (e.g. 500 for 500 g, 5 with unit \"kg\", 2 packs)."},"unit":{"type":"string","enum":["g","kg","oz","lb","mg","pkg","ml","cells","each"],"description":"Unit of amount. Fermentables and hops are stored in grams: send \"g\" (default), \"kg\", \"oz\" or \"lb\". Yeast counts in \"pkg\" (packs, default), \"ml\", \"g\" or \"cells\"; misc in \"g\", \"ml\", \"each\" or \"mg\" (default: the ingredient's own unit)."},"form":{"type":"string","description":"Hops: \"pellet\" (default), \"whole\", \"cryo\" or \"extract\". Yeast: \"dry\" or \"liquid\" (default from the yeast)."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Hops: alpha acid % wanted/offered (e.g. 13.2)."},"harvest_year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Hops: crop year."},"estimated_cost":{"type":"number","minimum":0,"description":"Expected price for the whole line, user's currency."},"price_paid":{"type":"number","minimum":0,"description":"Actual price for the whole line, user's currency (e.g. from the invoice)."},"notes":{"type":"string","maxLength":500,"description":"Free text for the line."}},"required":["ingredient","amount"],"additionalProperties":false},"maxItems":100,"description":"Create only: lines for the new order. Each: {ingredient (name or id), amount, unit?, type?, form?, alpha_acid_pct?, harvest_year?, estimated_cost?, price_paid?, notes?}, e.g. [{\"ingredient\": \"Pale Ale Malt\", \"amount\": 1, \"unit\": \"kg\"}]."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"supplier":{"type":"string"},"status":{"type":"string","enum":["draft","ordered","partial","received"]},"ordered_date":{"type":"string"},"expected_date":{"type":"string"},"received_date":{"type":"string"},"shipping_cost":{"type":"number"},"notes":{"type":"string"},"item_count":{"type":"integer"},"arrived_count":{"type":"integer"},"items_cost":{"type":"number","description":"Sum of the line prices that are set, user's currency."},"total_cost":{"type":"number","description":"items_cost plus shipping."},"next_step":{"type":"string","enum":["add_items","mark_ordered","receive","mark_received"],"description":"What to do next: add_items (edit_order_items), mark_ordered (save_order status \"ordered\"), receive (receive_order), mark_received (save_order status \"received\")."},"free_text_items":{"type":"array","items":{"type":"string"},"description":"Lines without a linked ingredient: they are skipped when booking into stock."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Order line id (item in edit_order_items / receive_order)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string","description":"Missing for free-text lines; those cannot be booked into stock."},"form":{"type":"string"},"alpha_acid_pct":{"type":"number"},"harvest_year":{"type":"integer"},"amount":{"type":"number","description":"Amount needed/requested, in unit."},"ordered_amount":{"type":"number","description":"Amount actually ordered, when it differs from amount."},"unit":{"type":"string"},"received":{"type":"number"},"remaining":{"type":"number","description":"Still to arrive."},"arrival":{"type":"string","enum":["pending","partial","arrived"]},"estimated_cost":{"type":"number"},"price_paid":{"type":"number","description":"Price for the whole line."},"notes":{"type":"string"}},"required":["id","type","name","amount","unit","received","remaining","arrival"]}}},"required":["id","name","status","item_count","arrived_count","items"]},"created":{"type":"boolean"},"note":{"type":"string"}},"required":["order","created"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/edit_order_items":{"post":{"operationId":"edit_order_items","tags":["Actions: Inventory"],"summary":"Add, change or remove order lines","description":"Change the lines of one order in a single call: add new lines (ingredient by name or id; a line for the same ingredient, form and unit is merged by adding the amounts), update lines (amount, ordered_amount, price_paid from the invoice, estimated_cost, notes) and remove lines. Amounts: fermentables/hops in g (default) or kg (the line keeps g or kg; oz/lb are converted to g); yeast in pkg by default; misc in the ingredient's unit. Prices are per whole line in the user's currency. Lines are referenced by line id or ingredient name. To book arrived lines into stock use receive_order.\n\nNeeds the plan feature `orders`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","feature":"orders","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"string","description":"The order: its id (from get_orders) or its exact name (e.g. \"Hopfen der Welt November\"). Case does not matter."},"add":{"type":"array","items":{"type":"object","properties":{"ingredient":{"type":"string","description":"Ingredient id or exact name from the user's picker (e.g. \"Citra\"). An ingredient that is not in the picker can still be ordered as a free-text line: pass its name and type (it is then not linked, so it cannot be booked into stock until linked)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount to buy, in unit (e.g. 500 for 500 g, 5 with unit \"kg\", 2 packs)."},"unit":{"type":"string","enum":["g","kg","oz","lb","mg","pkg","ml","cells","each"],"description":"Unit of amount. Fermentables and hops are stored in grams: send \"g\" (default), \"kg\", \"oz\" or \"lb\". Yeast counts in \"pkg\" (packs, default), \"ml\", \"g\" or \"cells\"; misc in \"g\", \"ml\", \"each\" or \"mg\" (default: the ingredient's own unit)."},"form":{"type":"string","description":"Hops: \"pellet\" (default), \"whole\", \"cryo\" or \"extract\". Yeast: \"dry\" or \"liquid\" (default from the yeast)."},"alpha_acid_pct":{"type":"number","minimum":0,"maximum":30,"description":"Hops: alpha acid % wanted/offered (e.g. 13.2)."},"harvest_year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Hops: crop year."},"estimated_cost":{"type":"number","minimum":0,"description":"Expected price for the whole line, user's currency."},"price_paid":{"type":"number","minimum":0,"description":"Actual price for the whole line, user's currency (e.g. from the invoice)."},"notes":{"type":"string","maxLength":500,"description":"Free text for the line."}},"required":["ingredient","amount"],"additionalProperties":false},"maxItems":100,"description":"New lines. Each: {ingredient (name or id), amount, unit?, type?, form?, alpha_acid_pct?, harvest_year?, estimated_cost?, price_paid?, notes?}, e.g. [{\"ingredient\": \"Citra\", \"amount\": 500}, {\"ingredient\": \"Pilsner Malt\", \"amount\": 25, \"unit\": \"kg\"}]."},"update":{"type":"array","items":{"type":"object","properties":{"item":{"type":"string","description":"The order line: its id (from get_orders with order) or the ingredient name on it (e.g. \"Citra\")."},"amount":{"type":"number","exclusiveMinimum":0,"description":"New needed amount, in unit (default: the line's unit)."},"ordered_amount":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Amount actually ordered when it differs (pack sizes), in the line's unit; null clears it."},"unit":{"type":"string","enum":["g","kg","oz","lb","mg","pkg","ml","cells","each"],"description":"Unit of amount. Fermentables and hops are stored in grams: send \"g\" (default), \"kg\", \"oz\" or \"lb\". Yeast counts in \"pkg\" (packs, default), \"ml\", \"g\" or \"cells\"; misc in \"g\", \"ml\", \"each\" or \"mg\" (default: the ingredient's own unit)."},"price_paid":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Price for the whole line, user's currency; null clears it."},"estimated_cost":{"type":"number","minimum":0,"description":"Expected price for the whole line."},"notes":{"type":"string","maxLength":500,"description":"Free text for the line."}},"required":["item"],"additionalProperties":false},"maxItems":100,"description":"Changes to existing lines. Each: {item (line id or ingredient name), amount?, ordered_amount?, unit?, price_paid?, estimated_cost?, notes?}, e.g. [{\"item\": \"Citra\", \"price_paid\": 18.5}]."},"remove":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Lines to take off the order. The order line: its id (from get_orders with order) or the ingredient name on it (e.g. \"Citra\")."}},"required":["order"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"supplier":{"type":"string"},"status":{"type":"string","enum":["draft","ordered","partial","received"]},"ordered_date":{"type":"string"},"expected_date":{"type":"string"},"received_date":{"type":"string"},"shipping_cost":{"type":"number"},"notes":{"type":"string"},"item_count":{"type":"integer"},"arrived_count":{"type":"integer"},"items_cost":{"type":"number","description":"Sum of the line prices that are set, user's currency."},"total_cost":{"type":"number","description":"items_cost plus shipping."},"next_step":{"type":"string","enum":["add_items","mark_ordered","receive","mark_received"],"description":"What to do next: add_items (edit_order_items), mark_ordered (save_order status \"ordered\"), receive (receive_order), mark_received (save_order status \"received\")."},"free_text_items":{"type":"array","items":{"type":"string"},"description":"Lines without a linked ingredient: they are skipped when booking into stock."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Order line id (item in edit_order_items / receive_order)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string","description":"Missing for free-text lines; those cannot be booked into stock."},"form":{"type":"string"},"alpha_acid_pct":{"type":"number"},"harvest_year":{"type":"integer"},"amount":{"type":"number","description":"Amount needed/requested, in unit."},"ordered_amount":{"type":"number","description":"Amount actually ordered, when it differs from amount."},"unit":{"type":"string"},"received":{"type":"number"},"remaining":{"type":"number","description":"Still to arrive."},"arrival":{"type":"string","enum":["pending","partial","arrived"]},"estimated_cost":{"type":"number"},"price_paid":{"type":"number","description":"Price for the whole line."},"notes":{"type":"string"}},"required":["id","type","name","amount","unit","received","remaining","arrival"]}}},"required":["id","name","status","item_count","arrived_count","items"]}},"required":["order"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/receive_order":{"post":{"operationId":"receive_order","tags":["Actions: Inventory"],"summary":"Receive an order into stock","description":"Mark an order's lines as arrived and book them into the ingredient stock (\"the order from Hopfen der Welt arrived\"). Without items: receives everything still outstanding on the order. With items: only those lines, with an optional amount (default: what is still outstanding, in the line's unit) and price_paid for the line. The result lists stock_changes (each changed stock row before/after). Booking into stock merges into the matching stock row and sets the price per kg / per unit from the line price plus its share of shipping, with the order's supplier on the stock row. Free-text lines are booked into the brewer's own library ingredient of the same name (subscribed or own ingredients, as in the pickers); lines with no such ingredient are marked received but not booked (see note). The order becomes \"partial\" or \"received\". Send add_to_stock: false for lines that should not go into the inventory.\n\nNeeds the plan feature `orders`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","feature":"orders","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"string","description":"The order: its id (from get_orders) or its exact name (e.g. \"Hopfen der Welt November\"). Case does not matter."},"items":{"type":"array","items":{"type":"object","properties":{"item":{"type":"string","description":"The order line: its id or the ingredient name on it (e.g. \"Citra\")."},"amount":{"type":"number","minimum":0,"description":"Amount that arrived, in the line's unit (default: everything outstanding)."},"price_paid":{"type":"number","minimum":0,"description":"Price for the whole line, user's currency (e.g. from the invoice)."},"add_to_stock":{"type":"boolean","description":"Book into the inventory (default true)."}},"required":["item"],"additionalProperties":false},"maxItems":100,"description":"Lines to receive; leave out to receive the whole order. Each: {item (line id or ingredient name), amount?, price_paid?, add_to_stock?}, e.g. [{\"item\": \"Citra\", \"price_paid\": 8.2}]."}},"required":["order"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"supplier":{"type":"string"},"status":{"type":"string","enum":["draft","ordered","partial","received"]},"ordered_date":{"type":"string"},"expected_date":{"type":"string"},"received_date":{"type":"string"},"shipping_cost":{"type":"number"},"notes":{"type":"string"},"item_count":{"type":"integer"},"arrived_count":{"type":"integer"},"items_cost":{"type":"number","description":"Sum of the line prices that are set, user's currency."},"total_cost":{"type":"number","description":"items_cost plus shipping."},"next_step":{"type":"string","enum":["add_items","mark_ordered","receive","mark_received"],"description":"What to do next: add_items (edit_order_items), mark_ordered (save_order status \"ordered\"), receive (receive_order), mark_received (save_order status \"received\")."},"free_text_items":{"type":"array","items":{"type":"string"},"description":"Lines without a linked ingredient: they are skipped when booking into stock."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Order line id (item in edit_order_items / receive_order)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string","description":"Missing for free-text lines; those cannot be booked into stock."},"form":{"type":"string"},"alpha_acid_pct":{"type":"number"},"harvest_year":{"type":"integer"},"amount":{"type":"number","description":"Amount needed/requested, in unit."},"ordered_amount":{"type":"number","description":"Amount actually ordered, when it differs from amount."},"unit":{"type":"string"},"received":{"type":"number"},"remaining":{"type":"number","description":"Still to arrive."},"arrival":{"type":"string","enum":["pending","partial","arrived"]},"estimated_cost":{"type":"number"},"price_paid":{"type":"number","description":"Price for the whole line."},"notes":{"type":"string"}},"required":["id","type","name","amount","unit","received","remaining","arrival"]}}},"required":["id","name","status","item_count","arrived_count","items"]},"booked_into_stock":{"type":"integer","description":"Lines added to the inventory."},"skipped_lines":{"type":"array","items":{"type":"string"},"description":"Lines received with add_to_stock false (not booked)."},"stock_changes":{"type":"array","items":{"type":"object","properties":{"stock":{"type":"string","description":"Stock row id (update_stock / remove_stock take it)."},"name":{"type":"string"},"type":{"type":"string"},"created":{"type":"boolean","description":"true: a new stock row; false: added to an existing row."},"amount_before":{"type":"number"},"amount_after":{"type":"number"},"unit":{"type":"string"},"cost_per_kg_before":{"type":"number"},"cost_per_kg_after":{"type":"number"},"cost_per_unit_before":{"type":"number"},"cost_per_unit_after":{"type":"number"}},"required":["stock","name","type","created","amount_after","unit"]},"description":"The stock rows this call changed, before and after (to undo: update_stock back to the before values, remove_stock for created rows)."},"note":{"type":"string"}},"required":["order","booked_into_stock"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_order":{"post":{"operationId":"delete_order","tags":["Actions: Inventory"],"summary":"Delete an order","description":"Delete one order with all its lines. Without confirm: true it only shows the order that would be deleted. Stock already booked in from it stays in the inventory. A finished order can also simply stay with status \"received\".\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Needs the plan feature `orders`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"destructive","required_scope":"inventory:write","feature":"orders","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"string","description":"The order: its id (from get_orders) or its exact name (e.g. \"Hopfen der Welt November\"). Case does not matter."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["order"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_planner":{"post":{"operationId":"get_planner","tags":["Actions: Inventory"],"summary":"Plan ingredients for planned brews","description":"What the planned brews need and what is missing (\"what am I short of for my planned brews?\"). Lists the brews with status planned and, per ingredient, the amount in stock, on order (orders with status ordered/partial), needed by the planned brews, what is left and what to buy (to_buy), with each brew's share. Default: every planned brew and only the ingredients they use; show: \"shortages\" for only what to buy, \"all\" to include stock no planned brew needs. Amounts are in each row's unit (grams for fermentables and hops). To turn the shortages into an order in one step use create_order_from_shortages.\n\nNeeds the plan feature `inventory_planner`. Scope: `inventory:read` (or `read`).","x-brewforge-action":{"toolset":"inventory","access":"read","required_scope":"inventory:read","feature":"inventory_planner","area":"inventory","idempotent":true},"security":[{"bearerAuth":["inventory:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brews":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Only these planned brews (ids, batch numbers or exact names, e.g. [\"#14\", \"Wiesn Festbier\"]). Default: every brew with status \"planned\"."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Ingredient type: \"fermentable\" (malts, sugars, extracts), \"hop\", \"yeast\" or \"misc\" (water agents, finings, spices, ...)."},"show":{"type":"string","enum":["needed","shortages","all"],"description":"\"needed\" (default): ingredients the included brews use; \"shortages\": only those to buy; \"all\": also stock nobody needs."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"planned_brews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"planned_date":{"type":"string"},"included":{"type":"boolean"}},"required":["id","name","included"]}},"shortages":{"type":"integer","description":"Ingredients to buy for the included brews."},"covered_by_open_orders":{"type":"integer","description":"Ingredients that are only enough once an open order arrives."},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"ingredient_id":{"type":"string","description":"Missing when the recipe's ingredient is not linked to the catalog (no stock lookup possible)."},"form":{"type":"string"},"alpha_acid_pct":{"type":"number"},"harvest_year":{"type":"integer"},"lab":{"type":"string"},"unit":{"type":"string","description":"Unit of every amount on this row (\"g\" for fermentables and hops)."},"in_stock":{"type":"number"},"on_order":{"type":"number","description":"On orders with status ordered/partial."},"needed":{"type":"number","description":"Needed by the included planned brews."},"left":{"type":"number","description":"in_stock + on_order - needed; negative means short."},"to_buy":{"type":"number","description":"Amount to buy (0 unless short)."},"status":{"type":"string","enum":["short","order","ok","unused"],"description":"short: not enough even with open orders; order: enough only once open orders arrive; ok; unused: in stock but no planned brew needs it."},"brews":{"type":"array","items":{"type":"object","properties":{"brew":{"type":"string"},"amount":{"type":"number"}},"required":["brew","amount"]},"description":"Amount per planned brew (included ones)."},"unlinked":{"type":"boolean","description":"true: the recipe line is not linked to an ingredient, so stock cannot be matched (in_stock is 0 even if a same-named stock row exists). Link it in the recipe to count its stock."}},"required":["name","type","unit","in_stock","on_order","needed","left","to_buy","status"]}},"unlinked_lines":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"}},"explanation":{"type":"string"},"fix":{"type":"string"}},"required":["names","explanation","fix"],"description":"Present when some recipe lines are not linked to a library ingredient (rows with unlinked: true), like the planner page shows them."}},"required":["planned_brews","shortages","covered_by_open_orders","items"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/create_order_from_shortages":{"post":{"operationId":"create_order_from_shortages","tags":["Actions: Inventory"],"summary":"Order what the planned brews are short of","description":"Put everything the planned brews are short of (the planner's to_buy amounts, after stock and open orders) on an order in one step: a new draft order, or an existing draft order (order). Defaults: all planned brews and all ingredient types; narrow with brews and type. Lines for the same ingredient merge. Returns the order with its lines; when nothing is short, nothing is created. Recipe lines not linked to an ingredient become free-text order lines (see free_text_items); receive_order links them by name when it can. Check get_planner first to see what will be ordered. Afterwards adjust lines with edit_order_items and mark it ordered with save_order.\n\nNeeds the plan feature `inventory_planner`. Scope: `inventory:write` (or `write`).","x-brewforge-action":{"toolset":"inventory","access":"write","required_scope":"inventory:write","feature":"inventory_planner","area":"inventory","idempotent":false},"security":[{"bearerAuth":["inventory:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brews":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Only these planned brews (ids, batch numbers or exact names, e.g. [\"#14\", \"Wiesn Festbier\"]). Default: every brew with status \"planned\"."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"],"description":"Only shortages of this ingredient type."},"order":{"type":"string","description":"Add to this existing order (id or exact name; should be a draft). Leave out to create a new order."},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Name of the new order (default \"Shortages YYYY-MM-DD\")."},"supplier":{"type":"string","maxLength":200,"description":"Shop for the new order."},"notes":{"type":"string","maxLength":1000,"description":"Notes for the new order."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean","description":"true when a new order was created."},"added_lines":{"type":"integer"},"order":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"supplier":{"type":"string"},"status":{"type":"string","enum":["draft","ordered","partial","received"]},"ordered_date":{"type":"string"},"expected_date":{"type":"string"},"received_date":{"type":"string"},"shipping_cost":{"type":"number"},"notes":{"type":"string"},"item_count":{"type":"integer"},"arrived_count":{"type":"integer"},"items_cost":{"type":"number","description":"Sum of the line prices that are set, user's currency."},"total_cost":{"type":"number","description":"items_cost plus shipping."},"next_step":{"type":"string","enum":["add_items","mark_ordered","receive","mark_received"],"description":"What to do next: add_items (edit_order_items), mark_ordered (save_order status \"ordered\"), receive (receive_order), mark_received (save_order status \"received\")."},"free_text_items":{"type":"array","items":{"type":"string"},"description":"Lines without a linked ingredient: they are skipped when booking into stock."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Order line id (item in edit_order_items / receive_order)."},"type":{"type":"string","enum":["fermentable","hop","yeast","misc"]},"name":{"type":"string"},"ingredient_id":{"type":"string","description":"Missing for free-text lines; those cannot be booked into stock."},"form":{"type":"string"},"alpha_acid_pct":{"type":"number"},"harvest_year":{"type":"integer"},"amount":{"type":"number","description":"Amount needed/requested, in unit."},"ordered_amount":{"type":"number","description":"Amount actually ordered, when it differs from amount."},"unit":{"type":"string"},"received":{"type":"number"},"remaining":{"type":"number","description":"Still to arrive."},"arrival":{"type":"string","enum":["pending","partial","arrived"]},"estimated_cost":{"type":"number"},"price_paid":{"type":"number","description":"Price for the whole line."},"notes":{"type":"string"}},"required":["id","type","name","amount","unit","received","remaining","arrival"]}}},"required":["id","name","status","item_count","arrived_count","items"]},"message":{"type":"string"}},"required":["created","added_lines"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/find_profiles":{"post":{"operationId":"find_profiles","tags":["Actions: Setup"],"summary":"Find profiles","description":"List the brewer's own profiles: equipment, mash, fermentation, water and hop stand curves, with the default of each kind marked is_default. Each row has a one-line summary (batch size, mash steps, fermentation stages, water ions). Use get_profile for every setting. With templates: true it lists the ready-made templates BrewForge offers instead (e.g. Grainfather G30, Burton on Trent water); add one with create_profile { template }. Volumes in litres, temperatures in °C, ions in mg/L.\n\nScope: `profiles:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"profiles:read","area":"profiles","idempotent":true},"security":[{"bearerAuth":["profiles:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["equipment","mash","fermentation","water","hop_stand"],"description":"Only profiles of this kind: \"equipment\", \"mash\", \"fermentation\", \"water\" or \"hop_stand\". Default: all kinds."},"query":{"type":"string","description":"Only profiles whose name contains this text. Example: \"grainfather\"."},"templates":{"type":"boolean","description":"true: list the templates BrewForge offers (not the brewer's own profiles). Default false."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 50)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["equipment","mash","fermentation","water","hop_stand"]},"name":{"type":"string"},"is_default":{"type":"boolean"},"batch_volume_l":{"type":"number"},"boil_time_min":{"type":"number"},"brewhouse_efficiency_pct":{"type":"number"},"steps":{"type":"string"},"stages":{"type":"string"},"ions_ppm":{"type":"string"},"points":{"type":"string"}},"required":["id","kind","name"],"description":"One profile: id, name, whether it is the default for new brews, and a short summary of its settings."}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_profile":{"post":{"operationId":"get_profile","tags":["Actions: Setup"],"summary":"Get a profile with all settings","description":"Every setting of one profile, in the same field names create_profile and update_profile take (litres, °C, minutes, mg/L). For equipment profiles, include: [\"evaporation\"] adds the measured boil-off of past brews with this equipment (pre/post-boil volumes) compared to the profile's boil_off_rate, to answer \"what is my real boil-off?\". Call find_profiles first if you do not know the name.\n\nScope: `profiles:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"profiles:read","area":"profiles","idempotent":true},"security":[{"bearerAuth":["profiles:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["equipment","mash","fermentation","water","hop_stand"],"description":"Profile kind: \"equipment\" (brewhouse volumes, losses, efficiency), \"mash\" (mash steps), \"fermentation\" (fermentation stages), \"water\" (water report ions) or \"hop_stand\" (temperature curve after flame-out)."},"profile":{"type":"string","description":"The profile: its id or its exact name (e.g. \"Grainfather G30\"). Case does not matter. Use find_profiles to see the names."},"include":{"type":"array","items":{"type":"string","enum":["evaporation"]},"description":"\"evaporation\" (equipment only): boil-off measured on past brews vs. the profile's rate."}},"required":["kind","profile"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/create_profile":{"post":{"operationId":"create_profile","tags":["Actions: Setup"],"summary":"Create a profile","description":"Create an equipment, mash, fermentation, water or hop stand profile. Three ways: (1) new, with the settings object of its kind (equipment needs only batch_volume_l, everything else gets the app defaults; mash needs steps; fermentation needs stages; hop_stand needs points; water takes the ions); (2) copy_from an own profile of the same kind (duplicate); (3) template: add a BrewForge template (see find_profiles { templates: true }). With copy_from or template, settings you send override the copy. is_default: true makes it the default for new brews. Example: {\"kind\": \"water\", \"name\": \"Tap water\", \"water\": {\"calcium_ppm\": 80, \"magnesium_ppm\": 12, \"sodium_ppm\": 20, \"chloride_ppm\": 60, \"sulfate_ppm\": 110, \"bicarbonate_ppm\": 150}}. Returns the profile with all settings (litres, °C, minutes, mg/L).\n\nNeeds the plan feature `profiles`. Scope: `profiles:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"write","required_scope":"profiles:write","feature":"profiles","area":"profiles","idempotent":false},"security":[{"bearerAuth":["profiles:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["equipment","mash","fermentation","water","hop_stand"],"description":"Profile kind: \"equipment\" (brewhouse volumes, losses, efficiency), \"mash\" (mash steps), \"fermentation\" (fermentation stages), \"water\" (water report ions) or \"hop_stand\" (temperature curve after flame-out)."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name of the new profile. Required unless template is given (then the template's name). Example: \"Grainfather G30 23 L\"."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Free text note (optional)."},"is_default":{"type":"boolean","description":"true: use it as the default for new brews (not for hop_stand)."},"copy_from":{"type":"string","description":"Duplicate this own profile of the same kind (id or exact name), then apply the settings you send."},"template":{"type":"string","description":"Add this BrewForge template (id or exact name, e.g. \"Grainfather G30\"); find_profiles { templates: true } lists them."},"equipment":{"type":"object","properties":{"batch_volume_l":{"type":"number","minimum":1,"description":"Target batch size in litres, measured where batch_volume_reference says. Required when creating. Example: 23."},"batch_volume_reference":{"type":"string","enum":["fermenter","kettle"],"description":"Where batch_volume_l is measured: \"fermenter\" (into the fermenter, default) or \"kettle\" (end of boil)."},"boil_time_min":{"type":"integer","minimum":0,"maximum":240,"description":"Default boil time in minutes (default 60)."},"boil_off_rate":{"type":"number","minimum":0,"description":"Boil-off per hour, in the unit of boil_off_rate_mode: litres per hour (default 4) or percent per hour. Example: 3."},"boil_off_rate_mode":{"type":"string","enum":["volume","percentage"],"description":"Unit of boil_off_rate: \"volume\" = litres per hour (default), \"percentage\" = % of pre-boil volume per hour. Changing only the mode converts the stored rate."},"pre_boil_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Fixed pre-boil volume (leave unset to let BrewForge calculate it), in litres. Example: 27."},{"type":"null"}],"description":"Fixed pre-boil volume (leave unset to let BrewForge calculate it), in litres. Example: 27."},"trub_chiller_loss_l":{"type":"number","minimum":0,"description":"Kettle loss to trub and chiller (default 1), in litres. Example: 1.5."},"mash_tun_dead_space_l":{"type":"number","minimum":0,"description":"Mash tun dead space below the outlet (default 0), in litres. Example: 0.5."},"mash_tun_loss_l":{"type":"number","minimum":0,"description":"Other mash tun losses (default 0), in litres. Example: 0."},"fermenter_loss_l":{"type":"number","minimum":0,"description":"Volume left in the fermenter at packaging (default 0.5), in litres. Example: 1."},"hlt_dead_space_l":{"type":"number","minimum":0,"description":"Hot liquor tank dead space (default 0), in litres. Example: 0."},"fermenter_top_up_l":{"type":"number","minimum":0,"description":"Water topped up in the fermenter (default 0), in litres. Example: 0."},"brewhouse_efficiency_pct":{"type":"number","minimum":0,"maximum":100,"description":"Brewhouse efficiency in percent (default 72). Example: 75."},"mash_efficiency_pct":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}],"description":"Mash efficiency in percent (optional). Example: 82."},"efficiency_display":{"type":"string","enum":["brewhouse","mash"],"description":"Which efficiency the recipe editor shows and edits: \"brewhouse\" (default) or \"mash\"."},"hop_utilization_pct":{"type":"number","minimum":0,"maximum":200,"description":"Hop utilization in percent of the formula's value (default 100)."},"mash_tun_max_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Usable mash tun capacity incl. grain displacement, in litres. Example: 40."},{"type":"null"}],"description":"Usable mash tun capacity incl. grain displacement, in litres. Example: 40."},"mash_tun_min_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Minimum mash tun fill incl. grain displacement, in litres. Example: 10."},{"type":"null"}],"description":"Minimum mash tun fill incl. grain displacement, in litres. Example: 10."},"hlt_max_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Most water the hot liquor tank heats per fill, in litres. Example: 30."},{"type":"null"}],"description":"Most water the hot liquor tank heats per fill, in litres. Example: 30."},"hlt_min_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Least water the hot liquor tank needs per fill, in litres. Example: 5."},{"type":"null"}],"description":"Least water the hot liquor tank needs per fill, in litres. Example: 5."},"kettle_max_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Maximum pre-boil kettle volume, in litres. Example: 35."},{"type":"null"}],"description":"Maximum pre-boil kettle volume, in litres. Example: 35."},"grain_absorption_l_per_kg":{"type":"number","minimum":0.5,"maximum":2,"description":"Water absorbed by the grain, litres per kg (default 1). Example: 0.8."},"water_to_grain_ratio_l_per_kg":{"type":"number","minimum":1,"maximum":10,"description":"Mash thickness, litres of strike water per kg grain (default 3). Example: 3.5."},"water_calculation":{"type":"string","enum":["default","batch_sparge","no_sparge","custom"],"description":"How strike and sparge water are split: \"default\" (fly sparge, mash thickness), \"batch_sparge\", \"no_sparge\" (full volume / BIAB) or \"custom\"."},"mash_water_min_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy minimum strike water; prefer mash_tun_min_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy minimum strike water; prefer mash_tun_min_volume_l, in litres. Example: 0."},"mash_water_max_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy maximum strike water; prefer mash_tun_max_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy maximum strike water; prefer mash_tun_max_volume_l, in litres. Example: 0."},"sparge_water_min_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy minimum sparge water; prefer hlt_min_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy minimum sparge water; prefer hlt_min_volume_l, in litres. Example: 0."},"sparge_water_max_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy maximum sparge water; prefer hlt_max_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy maximum sparge water; prefer hlt_max_volume_l, in litres. Example: 0."},"include_grain_volume":{"type":"boolean","description":"Legacy: whether mash_water_min_l/max_l include grain displacement."},"water_volume_display":{"type":"string","enum":["cold","hot"],"description":"Show water volumes cold (default) or hot (expanded)."},"overflow_target":{"type":"string","enum":["top_up","mash"],"description":"Where water that does not fit the vessels goes: \"top_up\" (fermenter top-up, default) or \"mash\"."},"altitude_m":{"type":"number","minimum":-500,"maximum":9000,"description":"Altitude in metres, lowers the boil temperature (default 0)."},"boil_temp_c":{"type":"number","minimum":80,"maximum":110,"description":"Boil temperature in °C (default 100)."},"hop_stand_temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Hop stand / whirlpool temperature in °C (default 80)."},"hop_stand_duration_min":{"type":"integer","minimum":0,"maximum":240,"description":"Hop stand duration in minutes (default 20)."},"grain_temp_c":{"type":"number","minimum":-20,"maximum":50,"description":"Grain temperature in °C for the strike temperature (default 20)."},"mash_tun_heat_capacity_l":{"type":"number","minimum":0,"description":"Mash tun heat capacity as litres of water equivalent (0 = ignore, default)."},"cooling_shrinkage_pct":{"type":"number","minimum":0,"maximum":10,"description":"Wort shrinkage on cooling in percent (default 4)."},"calculate_strike_temp":{"type":"boolean","description":"Calculate the strike water temperature (default true)."},"sparge_temp_c":{"type":"number","minimum":50,"maximum":100,"description":"Sparge water temperature in °C (default 76)."},"hop_stand_curve":{"type":["string","null"],"description":"Hop stand curve profile (id or exact name) the kettle follows after flame-out instead of a flat hop_stand_temp_c; null removes it. Example: \"No-chill cube\"."}},"additionalProperties":false,"description":"Equipment settings (kind equipment), only what you set. Fields include batch_volume_l, boil_time_min, boil_off_rate + boil_off_rate_mode (volume=L/h, percentage=%/h), brewhouse_efficiency_pct, trub_chiller_loss_l, fermenter_loss_l, kettle_max_volume_l / mash_tun_max_volume_l (vessel sizes), water_calculation, hop_stand_curve (get_profile lists all)."},"mash":{"type":"object","properties":{"grain_temp_c":{"type":"number","minimum":-20,"maximum":50,"description":"Grain temperature in °C (default 20)."},"steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Step name. Example: \"Saccharification\"."},"type":{"type":"string","enum":["infusion","temperature","decoction"],"description":"\"temperature\" (heat the mash, default), \"infusion\" (add hot water) or \"decoction\"."},"temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Rest temperature in °C. Example: 67."},"duration_min":{"type":"integer","minimum":0,"maximum":240,"description":"Rest duration in minutes. Example: 60."},"ramp_min":{"type":"integer","minimum":0,"maximum":120,"description":"Minutes to reach the rest temperature."},"water_l":{"type":"number","minimum":0,"description":"Infusion: litres of water added."},"infusion_water_temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Infusion: temperature of the added water in °C."},"decoction_volume_l":{"type":"number","minimum":0,"description":"Decoction: litres of thick mash pulled."},"decoction_return_temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Decoction: temperature when returned, °C."},"decoction_boil_min":{"type":"integer","minimum":0,"maximum":120,"description":"Decoction: boil time in minutes."},"decoction_volume_loss_l":{"type":"number","minimum":0,"description":"Decoction: litres lost while boiling."},"temp_loss_c_per_h":{"type":"number","minimum":0,"description":"Heat loss during the rest, °C per hour."}},"required":["name","temp_c","duration_min"],"additionalProperties":false},"minItems":1,"description":"Mash steps in order (replaces all steps). Required when creating a mash profile."}},"additionalProperties":false,"description":"Mash settings (kind mash): grain_temp_c and steps: [{name, temp_c, duration_min, type?: \"temperature\"|\"infusion\"|\"decoction\", ramp_min?}]. Example: {\"steps\": [{\"name\": \"Saccharification\", \"temp_c\": 67, \"duration_min\": 60}]}."},"fermentation":{"type":"object","properties":{"stages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Stage name. Example: \"Primary\"."},"type":{"type":"string","enum":["primary","secondary","tertiary","cold_crash","conditioning","carbonation"],"description":"Stage type (default \"primary\")."},"temp_c":{"type":"number","minimum":-5,"maximum":40,"description":"Target temperature in °C. Example: 19."},"duration_days":{"type":"integer","minimum":0,"maximum":365,"description":"Duration in days. Example: 10."},"ramp_hours":{"type":"integer","minimum":0,"description":"Hours to ramp to the target temperature."},"pressure_psi":{"type":"number","minimum":0,"maximum":50,"description":"Head pressure in psi (pressure fermentation / spunding target)."},"spunding":{"type":"boolean","description":"Spunding on this primary/secondary/tertiary stage (needs pressure_psi; at most one stage)."},"spunding_safety_margin_points":{"type":"number","minimum":0,"description":"Close the spunding valve this many gravity points before FG (default 4)."}},"required":["name","temp_c","duration_days"],"additionalProperties":false},"minItems":1,"description":"Fermentation stages in order (replaces all stages)."}},"required":["stages"],"additionalProperties":false,"description":"Fermentation settings (kind fermentation): stages: [{name, temp_c, duration_days, type?: primary|secondary|cold_crash|conditioning|..., pressure_psi?, spunding?}]. Example: {\"stages\": [{\"name\": \"Primary\", \"temp_c\": 19, \"duration_days\": 10}]}."},"water":{"type":"object","properties":{"calcium_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Calcium (Ca) in mg/L (ppm). Example: 80."},"magnesium_ppm":{"type":"number","minimum":0,"maximum":200,"description":"Magnesium (Mg) in mg/L. Example: 12."},"sodium_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Sodium (Na) in mg/L. Example: 20."},"chloride_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Chloride (Cl) in mg/L. Example: 60."},"sulfate_ppm":{"type":"number","minimum":0,"maximum":1000,"description":"Sulfate (SO4) in mg/L. Example: 110."},"bicarbonate_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Bicarbonate (HCO3) in mg/L. Example: 150."},"ph":{"anyOf":[{"type":"number","minimum":3,"maximum":11},{"type":"null"}],"description":"Water pH (optional). Example: 7.6."},"conductivity_us_cm":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Conductivity in µS/cm (optional)."}},"additionalProperties":false,"description":"Water report (kind water), ions in mg/L (ppm): calcium_ppm, magnesium_ppm, sodium_ppm, chloride_ppm, sulfate_ppm, bicarbonate_ppm, ph, conductivity_us_cm. Example: {\"calcium_ppm\": 80, \"sulfate_ppm\": 110, \"bicarbonate_ppm\": 150}."},"hop_stand":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"time_min":{"type":"number","minimum":0,"maximum":240,"description":"Minutes after flame-out; the first point is 0."},"temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Wort temperature in °C at that time."}},"required":["time_min","temp_c"],"additionalProperties":false},"minItems":2,"description":"Temperature curve after flame-out, at least 2 points, first at time 0, times ascending. Example: [{time_min:0,temp_c:95},{time_min:30,temp_c:70}]."}},"required":["points"],"additionalProperties":false,"description":"Hop stand curve (kind hop_stand): points: [{time_min, temp_c}], first at time_min 0. Example: {\"points\": [{\"time_min\": 0, \"temp_c\": 95}, {\"time_min\": 30, \"temp_c\": 70}]}."}},"required":["kind"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_profile":{"post":{"operationId":"update_profile","tags":["Actions: Setup"],"summary":"Change a profile","description":"Change some settings of one own profile; everything you do not send stays as it is. Rename with name, make it the default for new brews with is_default: true. Settings go into the object of the profile's kind, e.g. {\"kind\": \"equipment\", \"profile\": \"Grainfather G30\", \"equipment\": {\"boil_off_rate\": 3.2}}. Mash steps, fermentation stages and hop stand points are replaced as a whole list. Brews keep their own copy of a profile: to push the change into planned brews afterwards, call apply_profile. Returns the profile with all settings.\n\nNeeds the plan feature `profiles`. Scope: `profiles:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"write","required_scope":"profiles:write","feature":"profiles","area":"profiles","idempotent":false},"security":[{"bearerAuth":["profiles:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["equipment","mash","fermentation","water","hop_stand"],"description":"Profile kind: \"equipment\" (brewhouse volumes, losses, efficiency), \"mash\" (mash steps), \"fermentation\" (fermentation stages), \"water\" (water report ions) or \"hop_stand\" (temperature curve after flame-out)."},"profile":{"type":"string","description":"The profile: its id or its exact name (e.g. \"Grainfather G30\"). Case does not matter. Use find_profiles to see the names."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"New name."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"New note; null clears it."},"is_default":{"type":"boolean","description":"true: make this the default for new brews (the previous default stops being one). Not for hop_stand."},"equipment":{"type":"object","properties":{"batch_volume_l":{"type":"number","minimum":1,"description":"Target batch size in litres, measured where batch_volume_reference says. Required when creating. Example: 23."},"batch_volume_reference":{"type":"string","enum":["fermenter","kettle"],"description":"Where batch_volume_l is measured: \"fermenter\" (into the fermenter, default) or \"kettle\" (end of boil)."},"boil_time_min":{"type":"integer","minimum":0,"maximum":240,"description":"Default boil time in minutes (default 60)."},"boil_off_rate":{"type":"number","minimum":0,"description":"Boil-off per hour, in the unit of boil_off_rate_mode: litres per hour (default 4) or percent per hour. Example: 3."},"boil_off_rate_mode":{"type":"string","enum":["volume","percentage"],"description":"Unit of boil_off_rate: \"volume\" = litres per hour (default), \"percentage\" = % of pre-boil volume per hour. Changing only the mode converts the stored rate."},"pre_boil_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Fixed pre-boil volume (leave unset to let BrewForge calculate it), in litres. Example: 27."},{"type":"null"}],"description":"Fixed pre-boil volume (leave unset to let BrewForge calculate it), in litres. Example: 27."},"trub_chiller_loss_l":{"type":"number","minimum":0,"description":"Kettle loss to trub and chiller (default 1), in litres. Example: 1.5."},"mash_tun_dead_space_l":{"type":"number","minimum":0,"description":"Mash tun dead space below the outlet (default 0), in litres. Example: 0.5."},"mash_tun_loss_l":{"type":"number","minimum":0,"description":"Other mash tun losses (default 0), in litres. Example: 0."},"fermenter_loss_l":{"type":"number","minimum":0,"description":"Volume left in the fermenter at packaging (default 0.5), in litres. Example: 1."},"hlt_dead_space_l":{"type":"number","minimum":0,"description":"Hot liquor tank dead space (default 0), in litres. Example: 0."},"fermenter_top_up_l":{"type":"number","minimum":0,"description":"Water topped up in the fermenter (default 0), in litres. Example: 0."},"brewhouse_efficiency_pct":{"type":"number","minimum":0,"maximum":100,"description":"Brewhouse efficiency in percent (default 72). Example: 75."},"mash_efficiency_pct":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}],"description":"Mash efficiency in percent (optional). Example: 82."},"efficiency_display":{"type":"string","enum":["brewhouse","mash"],"description":"Which efficiency the recipe editor shows and edits: \"brewhouse\" (default) or \"mash\"."},"hop_utilization_pct":{"type":"number","minimum":0,"maximum":200,"description":"Hop utilization in percent of the formula's value (default 100)."},"mash_tun_max_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Usable mash tun capacity incl. grain displacement, in litres. Example: 40."},{"type":"null"}],"description":"Usable mash tun capacity incl. grain displacement, in litres. Example: 40."},"mash_tun_min_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Minimum mash tun fill incl. grain displacement, in litres. Example: 10."},{"type":"null"}],"description":"Minimum mash tun fill incl. grain displacement, in litres. Example: 10."},"hlt_max_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Most water the hot liquor tank heats per fill, in litres. Example: 30."},{"type":"null"}],"description":"Most water the hot liquor tank heats per fill, in litres. Example: 30."},"hlt_min_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Least water the hot liquor tank needs per fill, in litres. Example: 5."},{"type":"null"}],"description":"Least water the hot liquor tank needs per fill, in litres. Example: 5."},"kettle_max_volume_l":{"anyOf":[{"type":"number","minimum":0,"description":"Maximum pre-boil kettle volume, in litres. Example: 35."},{"type":"null"}],"description":"Maximum pre-boil kettle volume, in litres. Example: 35."},"grain_absorption_l_per_kg":{"type":"number","minimum":0.5,"maximum":2,"description":"Water absorbed by the grain, litres per kg (default 1). Example: 0.8."},"water_to_grain_ratio_l_per_kg":{"type":"number","minimum":1,"maximum":10,"description":"Mash thickness, litres of strike water per kg grain (default 3). Example: 3.5."},"water_calculation":{"type":"string","enum":["default","batch_sparge","no_sparge","custom"],"description":"How strike and sparge water are split: \"default\" (fly sparge, mash thickness), \"batch_sparge\", \"no_sparge\" (full volume / BIAB) or \"custom\"."},"mash_water_min_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy minimum strike water; prefer mash_tun_min_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy minimum strike water; prefer mash_tun_min_volume_l, in litres. Example: 0."},"mash_water_max_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy maximum strike water; prefer mash_tun_max_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy maximum strike water; prefer mash_tun_max_volume_l, in litres. Example: 0."},"sparge_water_min_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy minimum sparge water; prefer hlt_min_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy minimum sparge water; prefer hlt_min_volume_l, in litres. Example: 0."},"sparge_water_max_l":{"anyOf":[{"type":"number","minimum":0,"description":"Legacy maximum sparge water; prefer hlt_max_volume_l, in litres. Example: 0."},{"type":"null"}],"description":"Legacy maximum sparge water; prefer hlt_max_volume_l, in litres. Example: 0."},"include_grain_volume":{"type":"boolean","description":"Legacy: whether mash_water_min_l/max_l include grain displacement."},"water_volume_display":{"type":"string","enum":["cold","hot"],"description":"Show water volumes cold (default) or hot (expanded)."},"overflow_target":{"type":"string","enum":["top_up","mash"],"description":"Where water that does not fit the vessels goes: \"top_up\" (fermenter top-up, default) or \"mash\"."},"altitude_m":{"type":"number","minimum":-500,"maximum":9000,"description":"Altitude in metres, lowers the boil temperature (default 0)."},"boil_temp_c":{"type":"number","minimum":80,"maximum":110,"description":"Boil temperature in °C (default 100)."},"hop_stand_temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Hop stand / whirlpool temperature in °C (default 80)."},"hop_stand_duration_min":{"type":"integer","minimum":0,"maximum":240,"description":"Hop stand duration in minutes (default 20)."},"grain_temp_c":{"type":"number","minimum":-20,"maximum":50,"description":"Grain temperature in °C for the strike temperature (default 20)."},"mash_tun_heat_capacity_l":{"type":"number","minimum":0,"description":"Mash tun heat capacity as litres of water equivalent (0 = ignore, default)."},"cooling_shrinkage_pct":{"type":"number","minimum":0,"maximum":10,"description":"Wort shrinkage on cooling in percent (default 4)."},"calculate_strike_temp":{"type":"boolean","description":"Calculate the strike water temperature (default true)."},"sparge_temp_c":{"type":"number","minimum":50,"maximum":100,"description":"Sparge water temperature in °C (default 76)."},"hop_stand_curve":{"type":["string","null"],"description":"Hop stand curve profile (id or exact name) the kettle follows after flame-out instead of a flat hop_stand_temp_c; null removes it. Example: \"No-chill cube\"."}},"additionalProperties":false,"description":"Equipment settings (kind equipment), only what you set. Fields include batch_volume_l, boil_time_min, boil_off_rate + boil_off_rate_mode (volume=L/h, percentage=%/h), brewhouse_efficiency_pct, trub_chiller_loss_l, fermenter_loss_l, kettle_max_volume_l / mash_tun_max_volume_l (vessel sizes), water_calculation, hop_stand_curve (get_profile lists all)."},"mash":{"type":"object","properties":{"grain_temp_c":{"type":"number","minimum":-20,"maximum":50,"description":"Grain temperature in °C (default 20)."},"steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Step name. Example: \"Saccharification\"."},"type":{"type":"string","enum":["infusion","temperature","decoction"],"description":"\"temperature\" (heat the mash, default), \"infusion\" (add hot water) or \"decoction\"."},"temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Rest temperature in °C. Example: 67."},"duration_min":{"type":"integer","minimum":0,"maximum":240,"description":"Rest duration in minutes. Example: 60."},"ramp_min":{"type":"integer","minimum":0,"maximum":120,"description":"Minutes to reach the rest temperature."},"water_l":{"type":"number","minimum":0,"description":"Infusion: litres of water added."},"infusion_water_temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Infusion: temperature of the added water in °C."},"decoction_volume_l":{"type":"number","minimum":0,"description":"Decoction: litres of thick mash pulled."},"decoction_return_temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Decoction: temperature when returned, °C."},"decoction_boil_min":{"type":"integer","minimum":0,"maximum":120,"description":"Decoction: boil time in minutes."},"decoction_volume_loss_l":{"type":"number","minimum":0,"description":"Decoction: litres lost while boiling."},"temp_loss_c_per_h":{"type":"number","minimum":0,"description":"Heat loss during the rest, °C per hour."}},"required":["name","temp_c","duration_min"],"additionalProperties":false},"minItems":1,"description":"Mash steps in order (replaces all steps). Required when creating a mash profile."}},"additionalProperties":false,"description":"Mash settings (kind mash): grain_temp_c and steps: [{name, temp_c, duration_min, type?: \"temperature\"|\"infusion\"|\"decoction\", ramp_min?}]. Example: {\"steps\": [{\"name\": \"Saccharification\", \"temp_c\": 67, \"duration_min\": 60}]}."},"fermentation":{"type":"object","properties":{"stages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Stage name. Example: \"Primary\"."},"type":{"type":"string","enum":["primary","secondary","tertiary","cold_crash","conditioning","carbonation"],"description":"Stage type (default \"primary\")."},"temp_c":{"type":"number","minimum":-5,"maximum":40,"description":"Target temperature in °C. Example: 19."},"duration_days":{"type":"integer","minimum":0,"maximum":365,"description":"Duration in days. Example: 10."},"ramp_hours":{"type":"integer","minimum":0,"description":"Hours to ramp to the target temperature."},"pressure_psi":{"type":"number","minimum":0,"maximum":50,"description":"Head pressure in psi (pressure fermentation / spunding target)."},"spunding":{"type":"boolean","description":"Spunding on this primary/secondary/tertiary stage (needs pressure_psi; at most one stage)."},"spunding_safety_margin_points":{"type":"number","minimum":0,"description":"Close the spunding valve this many gravity points before FG (default 4)."}},"required":["name","temp_c","duration_days"],"additionalProperties":false},"minItems":1,"description":"Fermentation stages in order (replaces all stages)."}},"required":["stages"],"additionalProperties":false,"description":"Fermentation settings (kind fermentation): stages: [{name, temp_c, duration_days, type?: primary|secondary|cold_crash|conditioning|..., pressure_psi?, spunding?}]. Example: {\"stages\": [{\"name\": \"Primary\", \"temp_c\": 19, \"duration_days\": 10}]}."},"water":{"type":"object","properties":{"calcium_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Calcium (Ca) in mg/L (ppm). Example: 80."},"magnesium_ppm":{"type":"number","minimum":0,"maximum":200,"description":"Magnesium (Mg) in mg/L. Example: 12."},"sodium_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Sodium (Na) in mg/L. Example: 20."},"chloride_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Chloride (Cl) in mg/L. Example: 60."},"sulfate_ppm":{"type":"number","minimum":0,"maximum":1000,"description":"Sulfate (SO4) in mg/L. Example: 110."},"bicarbonate_ppm":{"type":"number","minimum":0,"maximum":500,"description":"Bicarbonate (HCO3) in mg/L. Example: 150."},"ph":{"anyOf":[{"type":"number","minimum":3,"maximum":11},{"type":"null"}],"description":"Water pH (optional). Example: 7.6."},"conductivity_us_cm":{"anyOf":[{"type":"number","minimum":0,"maximum":5000},{"type":"null"}],"description":"Conductivity in µS/cm (optional)."}},"additionalProperties":false,"description":"Water report (kind water), ions in mg/L (ppm): calcium_ppm, magnesium_ppm, sodium_ppm, chloride_ppm, sulfate_ppm, bicarbonate_ppm, ph, conductivity_us_cm. Example: {\"calcium_ppm\": 80, \"sulfate_ppm\": 110, \"bicarbonate_ppm\": 150}."},"hop_stand":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"time_min":{"type":"number","minimum":0,"maximum":240,"description":"Minutes after flame-out; the first point is 0."},"temp_c":{"type":"number","minimum":0,"maximum":100,"description":"Wort temperature in °C at that time."}},"required":["time_min","temp_c"],"additionalProperties":false},"minItems":2,"description":"Temperature curve after flame-out, at least 2 points, first at time 0, times ascending. Example: [{time_min:0,temp_c:95},{time_min:30,temp_c:70}]."}},"required":["points"],"additionalProperties":false,"description":"Hop stand curve (kind hop_stand): points: [{time_min, temp_c}], first at time_min 0. Example: {\"points\": [{\"time_min\": 0, \"temp_c\": 95}, {\"time_min\": 30, \"temp_c\": 70}]}."}},"required":["kind","profile"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_profile":{"post":{"operationId":"delete_profile","tags":["Actions: Setup"],"summary":"Delete a profile","description":"Permanently delete one own profile (equipment, mash, fermentation, water or hop stand curve). Without confirm: true it only shows what would be deleted. Brews keep their own copy of the settings, so no brew changes; they just stop being linked to it. Deleting the default leaves the kind without a default until you set one (update_profile is_default).\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Needs the plan feature `profiles`. Scope: `profiles:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"destructive","required_scope":"profiles:write","feature":"profiles","area":"profiles","idempotent":false},"security":[{"bearerAuth":["profiles:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["equipment","mash","fermentation","water","hop_stand"],"description":"Profile kind: \"equipment\" (brewhouse volumes, losses, efficiency), \"mash\" (mash steps), \"fermentation\" (fermentation stages), \"water\" (water report ions) or \"hop_stand\" (temperature curve after flame-out)."},"profile":{"type":"string","description":"The profile: its id or its exact name (e.g. \"Grainfather G30\"). Case does not matter. Use find_profiles to see the names."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["kind","profile"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/apply_profile":{"post":{"operationId":"apply_profile","tags":["Actions: Setup"],"summary":"Apply a profile to brews","description":"Push an equipment, mash or fermentation profile into brews. Brews keep their own copy of profiles, so changing a profile does not change existing brews until you apply it. With brew: replace that one brew's equipment / mash steps / fermentation stages with the profile (equipment with scale_recipe: true also scales the ingredient amounts to the new batch size; idea/planned brews only). Without brew: refresh every idea/planned brew that is linked to this profile. Without confirm: true it only returns how many brews would change. Imported brews get a new version instead of being changed.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Needs the plan feature `profiles`. Scope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"destructive","required_scope":"brews:write","feature":"profiles","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["equipment","mash","fermentation"],"description":"\"equipment\", \"mash\" or \"fermentation\" (water and hop stand profiles are chosen in the recipe)."},"profile":{"type":"string","description":"The profile: its id or its exact name (e.g. \"Grainfather G30\"). Case does not matter. Use find_profiles to see the names."},"brew":{"type":"string","description":"Only this brew. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter. Omit to update all linked idea/planned brews."},"scale_recipe":{"type":"boolean","description":"Equipment with one brew only: also scale ingredient amounts to the profile's batch size (default false)."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["kind","profile"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/find_styles":{"post":{"operationId":"find_styles","tags":["Actions: Setup"],"summary":"Find beer styles","description":"Search beer styles by name, style number or category: the BJCP 2021 library (source \"library\", id = style number like \"21A\") and the brewer's own styles (source \"mine\"). Each row has the style's ranges as [min, max]: og_sg / fg_sg (SG), ibu, color_ebc (EBC, as brews report color) and color_srm (SRM, as in the guidelines), abv_pct. Example: {\"query\": \"ipa\"} or {\"category\": \"Pale Bitter European Beer\"}. To use a library style as a base for your own, call save_style { from_library }.\n\nScope: `styles:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"styles:read","area":"styles","idempotent":true},"security":[{"bearerAuth":["styles:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Text in the name or style number, case-insensitive. Example: \"hazy\" or \"21B\"."},"category":{"type":"string","description":"Text in the category name. Example: \"IPA\" or \"Strong Belgian\"."},"source":{"type":"string","enum":["all","library","mine"],"description":"\"library\" (BJCP 2021), \"mine\" (own styles) or \"all\" (default; own styles first)."},"include_description":{"type":"boolean","description":"true: add each style's description text (longer result). Default false."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 20)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["library","mine"]},"name":{"type":"string"},"number":{"type":"string"},"category":{"type":"string"},"guidelines":{"type":"string"},"og_sg":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"fg_sg":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"ibu":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"color_ebc":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"color_srm":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"abv_pct":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"description":{"type":"string"}},"required":["id","source","name"],"description":"A style with its ranges as [min, max]: OG/FG in SG, IBU, color in EBC (color_ebc, same unit as brews) and SRM (color_srm, as in the BJCP guidelines), ABV in %."}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_style":{"post":{"operationId":"save_style","tags":["Actions: Setup"],"summary":"Create or change an own style","description":"Create or change one of the brewer's own beer styles (the BJCP library itself is read-only). Three ways: (1) style given: change that own style, only the fields you send; (2) from_library: copy a BJCP 2021 style (e.g. \"21A\") as an own style, then apply the fields you send; (3) neither: create a new style (name required). Ranges: og/fg in SG (e.g. og_min_sg 1.056), ibu, color in SRM (or EBC with color_unit \"ebc\"), abv in %. null clears a value. Returns the saved style with its ranges.\n\nScope: `styles:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"write","required_scope":"styles:write","area":"styles","idempotent":false},"security":[{"bearerAuth":["styles:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"style":{"type":"string","description":"Change this own style. One of the brewer's own styles: its id or its exact name (e.g. \"My Hazy IPA\"). Case does not matter. Use find_styles { source: \"mine\" } to see them. Omit to create one."},"from_library":{"type":"string","description":"Create an own copy of this BJCP 2021 library style: style number or exact name, e.g. \"21A\" or \"American IPA\"."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Style name. Required for a brand-new style. Example: \"House Pale Ale\"."},"number":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Style number, e.g. \"21A\" (optional)."},"category":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Category, e.g. \"IPA\" (optional)."},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Description text (optional)."},"og_min_sg":{"type":["number","null"],"description":"Minimum original gravity in SG, e.g. 1.050."},"og_max_sg":{"type":["number","null"],"description":"Maximum original gravity in SG, e.g. 1.065."},"fg_min_sg":{"type":["number","null"],"description":"Minimum final gravity in SG, e.g. 1.008."},"fg_max_sg":{"type":["number","null"],"description":"Maximum final gravity in SG, e.g. 1.014."},"ibu_min":{"type":["number","null"],"description":"Minimum bitterness in IBU, e.g. 40."},"ibu_max":{"type":["number","null"],"description":"Maximum bitterness in IBU, e.g. 70."},"color_min":{"type":["number","null"],"description":"Minimum color in color_unit (SRM by default), e.g. 6."},"color_max":{"type":["number","null"],"description":"Maximum color in color_unit (SRM by default), e.g. 14."},"color_unit":{"type":"string","enum":["srm","ebc"],"description":"Unit of color_min / color_max: \"srm\" (default) or \"ebc\"."},"abv_min_pct":{"type":["number","null"],"description":"Minimum alcohol in % ABV, e.g. 5.5."},"abv_max_pct":{"type":["number","null"],"description":"Maximum alcohol in % ABV, e.g. 7.5."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"string","enum":["created","updated"]},"style":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["library","mine"]},"name":{"type":"string"},"number":{"type":"string"},"category":{"type":"string"},"guidelines":{"type":"string"},"og_sg":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"fg_sg":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"ibu":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"color_ebc":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"color_srm":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"abv_pct":{"type":"array","minItems":2,"maxItems":2,"items":[{"type":"number"},{"type":"number"}]},"description":{"type":"string"}},"required":["id","source","name"],"description":"A style with its ranges as [min, max]: OG/FG in SG, IBU, color in EBC (color_ebc, same unit as brews) and SRM (color_srm, as in the BJCP guidelines), ABV in %."}},"required":["saved","style"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_style":{"post":{"operationId":"delete_style","tags":["Actions: Setup"],"summary":"Delete an own style","description":"Permanently delete one of the brewer's own beer styles (library styles cannot be deleted). Without confirm: true it only shows what would be deleted. Recipes keep the style values they copied, so no brew changes.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `styles:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"destructive","required_scope":"styles:write","area":"styles","idempotent":false},"security":[{"bearerAuth":["styles:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"style":{"type":"string","description":"One of the brewer's own styles: its id or its exact name (e.g. \"My Hazy IPA\"). Case does not matter. Use find_styles { source: \"mine\" } to see them."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["style"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/list_custom_fields":{"post":{"operationId":"list_custom_fields","tags":["Actions: Setup"],"summary":"List custom field definitions","description":"The brewer's own custom fields: extra values they record on brews (scope \"brew\", shown in a section given by placement: brew_details, brew_day, fermentation, packaging, tasting) or on brew notes (scope \"brew_note\"). Each has a key, name, type (text, number, integer, date, time, datetime, boolean, select, url), choices for select fields, unit and default. Archived fields are hidden in the app; include_archived: true lists them too. Create or change them with save_custom_field.\n\nScope: `custom-fields:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"custom-fields:read","area":"custom-fields","idempotent":true},"security":[{"bearerAuth":["custom-fields:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include_archived":{"type":"boolean","description":"true: also list archived fields. Default false."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"scope":{"type":"string"},"placement":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"unit":{"type":"string"},"placeholder":{"type":"string"},"default_value":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"display_order":{"type":"integer"},"archived":{"type":"boolean"},"archived_at":{"type":"string"}},"required":["id","key","name","type","scope","display_order"]}}},"required":["items"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/save_custom_field":{"post":{"operationId":"save_custom_field","tags":["Actions: Setup"],"summary":"Create, change or archive a custom field","description":"Create a custom field definition (omit field) or change one (field = its key, name or id). Brew fields (scope \"brew\", default) need a placement: the brew page section they appear in. Brew note fields (scope \"brew_note\") have no placement. Type and scope are fixed after creation. archived: true hides a field in the app (values stay), false restores it; delete it for good with delete_custom_field. Example: {\"name\": \"Mash pH\", \"type\": \"number\", \"placement\": \"brew_day\", \"unit\": \"pH\"}. Values on brews are set with the brewing tools.\n\nScope: `custom-fields:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"write","required_scope":"custom-fields:write","area":"custom-fields","idempotent":false},"security":[{"bearerAuth":["custom-fields:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field":{"type":"string","description":"Change this field. The custom field: its id, key (e.g. \"mash-ph\") or exact name (e.g. \"Mash pH\"). Case does not matter. list_custom_fields shows them. Omit to create a new one."},"name":{"type":"string","minLength":1,"maxLength":50,"description":"Label shown in the app. Required when creating. Example: \"Mash pH\"."},"key":{"type":"string","description":"New fields only: stable key (lowercase, digits, dashes), e.g. \"mash-ph\". Default: made from the name."},"type":{"type":"string","enum":["text","number","integer","date","time","datetime","boolean","select","url"],"description":"New fields only: \"text\", \"number\", \"integer\", \"date\", \"time\", \"datetime\", \"boolean\", \"select\" or \"url\". Default \"text\"."},"scope":{"type":"string","enum":["brew","brew_note"],"description":"New fields only: \"brew\" (a value per brew, default) or \"brew_note\" (a value per brew note)."},"placement":{"type":"string","enum":["brew_details","brew_day","fermentation","packaging","tasting"],"description":"Brew fields: page section, \"brew_details\", \"brew_day\", \"fermentation\", \"packaging\" or \"tasting\". Required for new brew fields."},"choices":{"type":"array","items":{"type":"string","minLength":1},"minItems":2,"maxItems":20,"description":"Select fields: the options, 2-20. Example: [\"clear\", \"hazy\", \"murky\"]."},"unit":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Unit label for number fields, e.g. \"pH\" or \"g/L\"; null clears it."},"placeholder":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Hint text shown in the empty input; null clears it."},"default_value":{"anyOf":[{"type":["string","number","boolean"]},{"type":"null"}],"description":"Pre-filled value for new brews, matching the type (e.g. 5.4, true, \"clear\"); null clears it."},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Help text; null clears it."},"required":{"type":"boolean","description":"true: the app asks for a value."},"display_order":{"type":"integer","minimum":0,"description":"Position within its section, 0 first."},"archived":{"type":"boolean","description":"Existing fields: true archives (hides) it, false restores it."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"string","enum":["created","updated"]},"field":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"scope":{"type":"string"},"placement":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}},"unit":{"type":"string"},"placeholder":{"type":"string"},"default_value":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"display_order":{"type":"integer"},"archived":{"type":"boolean"},"archived_at":{"type":"string"}},"required":["id","key","name","type","scope","display_order"]}},"required":["saved","field"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_custom_field":{"post":{"operationId":"delete_custom_field","tags":["Actions: Setup"],"summary":"Delete a custom field for good","description":"Permanently delete a custom field definition and every value recorded for it on brews and brew notes. Without confirm: true it only returns the impact (how many brews and notes have a value). To only hide a field and keep its values, use save_custom_field { archived: true } instead.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `custom-fields:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"destructive","required_scope":"custom-fields:write","area":"custom-fields","idempotent":false},"security":[{"bearerAuth":["custom-fields:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field":{"type":"string","description":"The custom field: its id, key (e.g. \"mash-ph\") or exact name (e.g. \"Mash pH\"). Case does not matter. list_custom_fields shows them."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["field"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_preferences":{"post":{"operationId":"get_preferences","tags":["Actions: Setup"],"summary":"Get preferences","description":"The brewer's settings: units and formats the app shows (volume, weight, temperature, gravity, color, pressure, CO2, currency, date format), IBU formula, efficiency convention, language, brew-day recalculation mode, defaults for new brews (default profiles, brewer name, next batch number floor, default additions, default bittering hop) and the calendar feed (iCal URL and filters). Change them with update_preferences. Tools always take and return canonical units; these settings only say how the user reads values.\n\nScope: `settings:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"settings:read","area":"settings","idempotent":true},"security":[{"bearerAuth":["settings:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_preferences":{"post":{"operationId":"update_preferences","tags":["Actions: Setup"],"summary":"Change preferences","description":"Change the brewer's settings; only what you send changes. Units/formats: e.g. {\"volume_unit\": \"gallons\", \"temperature_unit\": \"fahrenheit\", \"gravity_format\": \"sg\"}. Defaults for new brews: default_equipment_profile / _mash_ / _fermentation_ / _water_profile (own profile by name), brewer_name, batch_number_floor, default_additions (replaces the list). Calendar: calendar_feed \"enable\" (returns the iCal URL), \"regenerate\" (new URL, old one stops working) or \"disable\", and calendar_feed_settings. Returns all preferences like get_preferences. To go back to the default units use reset_preferences.\n\nScope: `settings:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"write","required_scope":"settings:write","area":"settings","idempotent":false},"security":[{"bearerAuth":["settings:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"volume_unit":{"type":"string","enum":["liters","gallons"],"description":"Volumes: \"liters\" or \"gallons\" (US)."},"weight_unit":{"type":"string","enum":["kg","lb"],"description":"Weights: \"kg\" (kg/g) or \"lb\" (lb/oz)."},"temperature_unit":{"type":"string","enum":["celsius","fahrenheit"],"description":"Temperatures: \"celsius\" or \"fahrenheit\"."},"gravity_format":{"type":"string","enum":["sg","plato"],"description":"Gravity: \"sg\" (1.050) or \"plato\" (°P)."},"color_format":{"type":"string","enum":["srm","ebc"],"description":"Beer color: \"srm\" or \"ebc\"."},"pressure_unit":{"type":"string","enum":["psi","bar"],"description":"Pressure: \"psi\" or \"bar\"."},"co2_format":{"type":"string","enum":["volumes","gl"],"description":"Carbonation: \"volumes\" or \"gl\" (g/L)."},"currency":{"type":"string","enum":["EUR","USD"],"description":"Currency for costs: \"EUR\" or \"USD\"."},"date_format":{"type":"string","enum":["european","american"],"description":"Dates: \"european\" (31.12.2026) or \"american\" (12/31/2026)."},"ibu_formula":{"type":"string","enum":["tinseth","rager"],"description":"IBU formula: \"tinseth\" or \"rager\"."},"efficiency_convention":{"type":"string","enum":["international","sudhausausbeute"],"description":"Efficiency: \"international\" (brewhouse + mash efficiency) or \"sudhausausbeute\" (German convention)."},"language":{"type":"string","enum":["en","de"],"description":"App language: \"en\" or \"de\"."},"brew_day_recalculation":{"type":"string","enum":["keep_efficiency","keep_recipe_value"],"description":"When brew-day measurements differ: \"keep_efficiency\" (recalculate the targets with the planned efficiency) or \"keep_recipe_value\" (keep the recipe targets)."},"brewer_name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Brewer or brewery name printed on brew sheets and labels; null clears it."},"batch_number_floor":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"The next batch number is at least this (e.g. 100 to continue after an old system); null clears it."},"default_equipment_profile":{"type":"string","description":"Make this own equipment profile the default for new brews (id or exact name, e.g. \"Grainfather G30\")."},"default_mash_profile":{"type":"string","description":"Make this own mash profile the default for new brews (id or exact name, e.g. \"Single infusion 67 °C\")."},"default_fermentation_profile":{"type":"string","description":"Make this own fermentation profile the default for new brews (id or exact name, e.g. \"Ale 19 °C\")."},"default_water_profile":{"type":"string","description":"Make this own water profile the default for new brews (id or exact name, e.g. \"Tap water\")."},"default_additions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Ingredient name, e.g. \"Whirlfloc\" or \"Calcium chloride\"."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount per brew in unit, e.g. 1."},"unit":{"type":"string","enum":["g","mg","ml","tsp","tbsp","each"],"description":"Unit of amount."},"type":{"type":"string","enum":["water_agent","fining","flavor","spice","herb","fruit","nutrient","other"],"description":"Kind of addition."},"use":{"type":"string","enum":["mash","boil","whirlpool","primary","secondary","bottling"],"description":"When it is added."},"time_min":{"type":"number","minimum":0,"description":"mash/boil/whirlpool: minutes (e.g. 10 = last 10 min of the boil)."},"day":{"type":"number","minimum":0,"description":"primary/secondary/bottling: fermentation day it goes in."}},"required":["name","amount","unit","use"],"additionalProperties":false},"maxItems":30,"description":"Misc ingredients added to every new brew; replaces the whole list, [] clears it."},"clear_default_bittering_hop":{"type":"boolean","description":"true: forget the default bittering hop (it is set from the recipe editor's quick bittering)."},"cacl2_form":{"anyOf":[{"type":"string","enum":["anhydrous","dihydrate","liquid"]},{"type":"null"}],"description":"Form of the calcium chloride used for water salts; null = app default."},"cacl2_liquid_concentration_pct":{"type":"number","minimum":1,"maximum":100,"description":"Concentration in % when cacl2_form is \"liquid\", e.g. 33."},"calendar_feed":{"type":"string","enum":["enable","regenerate","disable"],"description":"\"enable\": turn the iCal feed on (URL in the result), \"regenerate\": new secret URL (the old one stops working), \"disable\": turn it off."},"calendar_feed_settings":{"type":"object","properties":{"statuses":{"type":"array","items":{"type":"string","enum":["idea","planned","brewing","fermenting","conditioning","completed","archived"]},"description":"Brew statuses whose events appear in the feed."},"event_types":{"type":"array","items":{"type":"string","enum":["brew_day","planned","packaging","fermentation_event"]},"description":"Event types in the feed: \"brew_day\", \"planned\" (planned brew days), \"packaging\", \"fermentation_event\" (fermentation steps)."},"vessel_events":{"type":"boolean","description":"Include cellar vessel occupied/free events."},"reminders":{"type":"boolean","description":"Include reminders."},"ready_by":{"type":"boolean","description":"Include ready-by / brew-by dates."}},"additionalProperties":false,"description":"Which events the iCal feed contains; only the fields you send change."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/reset_preferences":{"post":{"operationId":"reset_preferences","tags":["Actions: Setup"],"summary":"Reset preferences to defaults","description":"Reset the brewer's settings to BrewForge's defaults (litres, kg, °C, °Plato, EBC, psi, CO2 volumes, EUR, European dates, Tinseth, international efficiency) and clear brewer name, batch number floor, default additions, default bittering hop, brewery logo and water salt preferences. The language stays. Profiles and their defaults are not touched. Without confirm: true it lists exactly what would change. To change single settings use update_preferences instead.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `settings:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"destructive","required_scope":"settings:write","area":"settings","idempotent":false},"security":[{"bearerAuth":["settings:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_calendar":{"post":{"operationId":"get_calendar","tags":["Actions: Setup"],"summary":"Brewing calendar","description":"Events of the brewing calendar in a date range, as the app's calendar shows them: planned and actual brew days, fermentation steps (dry hop, cold crash, ...), packaging days, ready-by / brew-by dates, reminders and (with the cellar feature) when kegs and fermenters are occupied or free. Default range: 7 days ago to 60 days ahead. Example: {\"from\": \"2026-12-01\", \"to\": \"2026-12-31\", \"types\": [\"brew_day\", \"planned\"]}. The iCal subscription URL is in get_preferences (calendar_feed).\n\nScope: `brews:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"brews:read","area":"brews","idempotent":true},"security":[{"bearerAuth":["brews:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day, YYYY-MM-DD (default: 7 days ago)."},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day, YYYY-MM-DD (default: 60 days ahead). At most 400 days after from."},"types":{"type":"array","items":{"type":"string","enum":["brew_day","planned","packaging","fermentation_event","vessel_occupied","vessel_free","reminder","ready_by","brew_by"]},"description":"Only these event types: brew_day, planned, packaging, fermentation_event, ready_by, brew_by, reminder, vessel_occupied, vessel_free. Default: all."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Events in the range per type (all of them, also when events is truncated), e.g. {\"brew_day\": 2, \"packaging\": 1}."},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"end":{"type":"string"},"type":{"type":"string","enum":["brew_day","planned","packaging","fermentation_event","vessel_occupied","vessel_free","reminder","ready_by","brew_by"]},"title":{"type":"string"},"description":{"type":"string"},"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"batch_number":{"type":"integer"},"status":{"type":"string"}},"required":["id","name","status"]},"vessel":{"type":"string"}},"required":["date","type","title"]}},"truncated":{"type":"boolean"}},"required":["from","to","counts","events"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/run_calculator":{"post":{"operationId":"run_calculator","tags":["Actions: Setup"],"summary":"Run a brewing calculator","description":"BrewForge's brewing calculators: ABV, IBU, beer color, strike water, step mash, dilution, boil-off, hydrometer temperature correction, refractometer, priming sugar, force carbonation, spunding, yeast pitch rate, hop freshness and unit conversion. Use them instead of doing brewing math yourself. Call without calculator to get the list with each calculator's parameters and an example; then call with calculator and params. Example: {\"calculator\": \"priming-sugar\", \"params\": {\"volume\": 19, \"co2\": 2.4, \"beerTemp\": 18}}. Results carry their units.\n\nNeeds the plan feature `calculators`. Scope: `settings:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"settings:read","feature":"calculators","area":"settings","idempotent":true},"security":[{"bearerAuth":["settings:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"calculator":{"type":"string","description":"Calculator name from the list, e.g. \"priming-sugar\" or \"abv\". Omit to list all calculators with their parameters."},"params":{"type":"object","additionalProperties":{"type":["string","number","boolean"]},"description":"Parameters by name, as listed for the calculator, e.g. {\"og\": 1.052, \"fg\": 1.010}. Values are metric (L, °C, kg, g) and SG unless you pass the calculator's unit parameters (e.g. volumeUnit \"gal\", temperatureUnit \"F\") or units: \"imperial\"."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/list_imports":{"post":{"operationId":"list_imports","tags":["Actions: Setup"],"summary":"List import runs","description":"Recent imports from Brewfather (backup) and Kleiner Brauhelfer, newest first, with what each created (counts per kind: brews, profiles, inventory, ...) and whether it can still be undone (7 days after it finished). Undo one with undo_import. Imports themselves run in the app's import wizards (Settings → Import), which parse the files in the browser.\n\nScope: `settings:read` (or `read`).","x-brewforge-action":{"toolset":"setup","access":"read","required_scope":"settings:read","area":"settings","idempotent":true},"security":[{"bearerAuth":["settings:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["brewfather","kbh"],"description":"Only runs from \"brewfather\" or \"kbh\" (Kleiner Brauhelfer). Default: both."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["brewfather","kbh"]},"status":{"type":"string"},"started_at":{"type":"string"},"finished_at":{"type":"string"},"counts":{"type":"object","additionalProperties":{"type":"number"}},"can_undo":{"type":"boolean"},"undo_until":{"type":"string"}},"required":["id","source","status","started_at","can_undo","undo_until"]}}},"required":["items"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/undo_import":{"post":{"operationId":"undo_import","tags":["Actions: Setup"],"summary":"Undo an import run","description":"Remove everything one Brewfather or Kleiner Brauhelfer import run created (brews with their readings, profiles, styles, inventory, own ingredients) and revert the stock it added. Possible for 7 days after the import. Brews with beer still in the cellar and ingredients still in use are kept and listed. Without confirm: true it only shows what the run created. Get the run id from list_imports.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `settings:write` (or `write`).","x-brewforge-action":{"toolset":"setup","access":"destructive","required_scope":"settings:write","area":"settings","idempotent":false},"security":[{"bearerAuth":["settings:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"string","description":"Import run id from list_imports."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["run"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/browse_community":{"post":{"operationId":"browse_community","tags":["Actions: Community"],"summary":"Browse the community feed or discover brewers","description":"The BrewForge community. Without query/style: the feed of what the brewers the user follows brewed, packaged and shared (last 30 days, `days` for more), plus a few suggested brewers. With query and/or style (or view: \"discover\"): search other brewers' shared recipes by beer name, style or brewer name/handle (e.g. query \"hopfenhans\" or style \"German Pilsner\"), with suggested brewers. Use handles from the result with get_brewer_profile / interact_with_brewer, brew_id with cheer_brew, share_token with adopt_shared_recipe. Only brewers with an open profile appear.\n\nScope: `community:read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"community:read","area":"community","idempotent":true},"security":[{"bearerAuth":["community:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"view":{"type":"string","enum":["feed","discover"],"description":"\"feed\" (default) or \"discover\". Passing query or style switches to discover."},"query":{"type":"string","maxLength":80,"description":"Beer name, style or brewer name/handle to search for, e.g. \"pils\" or \"hopfenhans\"."},"style":{"type":"string","maxLength":80,"description":"Exact style name of shared recipes, e.g. \"American IPA\". The discover result lists available styles."},"days":{"type":"integer","minimum":30,"maximum":365,"description":"Feed only: days to look back, 30-365 (default 30)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"view":{"type":"string","enum":["feed","discover"]},"following":{"type":"integer","description":"How many brewers the user follows (feed)."},"entries":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["brewed","packaged","listed","milestone"],"description":"brewed, packaged, listed (recipe added to the profile) or milestone (every 10th brew)."},"date":{"type":"string","description":"YYYY-MM-DD"},"brewer":{"type":"object","properties":{"handle":{"type":"string","description":"Pass to get_brewer_profile or interact_with_brewer."},"name":{"type":"string"},"location":{"type":"string"}},"required":["handle","name"]},"brew_id":{"type":"string","description":"For cheer_brew."},"beer":{"type":"string"},"style":{"type":"string"},"milestone":{"type":"integer","description":"Brew count reached (milestones)."},"share_token":{"type":"string","description":"The recipe is shared: pass to adopt_shared_recipe to copy it."},"based_on":{"type":"string","description":"The brew is a copy of this brewer's shared recipe."},"cheers":{"type":"integer"},"cheered_by_you":{"type":"boolean"}},"required":["kind","date","brewer","brew_id","beer","cheers"]},"description":"Feed entries, newest first (max 50)."},"has_older":{"type":"boolean","description":"Feed: older entries exist; call again with a larger days."},"recipes":{"type":"array","items":{"type":"object","properties":{"brew_id":{"type":"string"},"name":{"type":"string"},"style":{"type":"string"},"brewer":{"type":"object","properties":{"handle":{"type":"string","description":"Pass to get_brewer_profile or interact_with_brewer."},"name":{"type":"string"},"location":{"type":"string"}},"required":["handle","name"]},"abv_pct":{"type":"number"},"ibu":{"type":"number"},"brewed_by":{"type":"integer","description":"Other brewers who brewed a copy."},"cheers":{"type":"integer"},"share_token":{"type":"string","description":"Pass to adopt_shared_recipe to copy the recipe into the user's brews."}},"required":["brew_id","name","brewer","brewed_by","cheers","share_token"]},"description":"Discover: shared recipes, most brewed/cheered first."},"styles":{"type":"array","items":{"type":"string"},"description":"Discover: styles of the matching recipes (values for style); all shared styles when nothing matched."},"suggested_brewers":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string","description":"Pass to get_brewer_profile or interact_with_brewer."},"name":{"type":"string"},"location":{"type":"string"},"styles":{"type":"array","items":{"type":"string"}},"listed_recipes":{"type":"integer"},"new_here":{"type":"boolean"}},"required":["handle","name","listed_recipes"]}},"note":{"type":"string"}},"required":["view","suggested_brewers"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_brewer_profile":{"post":{"operationId":"get_brewer_profile","tags":["Actions: Community"],"summary":"Get a brewer's community profile","description":"A brewer's community profile: bio, follower counts, whether the user follows them, the recipes they shared (share_token for adopt_shared_recipe) and their recent activity. Example: { \"brewer\": \"hopfenhans\" }. Without brewer: the user's OWN community profile with its settings (handle, visibility, bio, activity options; change them with update_community_profile), followers / following / blocked lists and recent community notices (follows, cheers, copies brewed).\n\nScope: `community:read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"community:read","area":"community","idempotent":true},"security":[{"bearerAuth":["community:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brewer":{"type":"string","description":"The brewer: their handle (with or without @, e.g. \"hopfenhans\") as shown by browse_community or get_brewer_profile, or their user id from a connections list. Omit for the user's own profile."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brewer":{"type":"object","properties":{"handle":{"type":"string"},"name":{"type":"string"},"location":{"type":"string"},"bio":{"type":"string"},"brewing_since":{"type":"integer"},"brewhouse":{"type":"string"},"url":{"type":"string","description":"Public profile page."}},"required":["name"]},"is_you":{"type":"boolean"},"you_follow":{"type":"boolean"},"followers":{"type":"integer"},"following":{"type":"integer"},"brews_brewed":{"type":"integer"},"shared_recipes":{"type":"array","items":{"type":"object","properties":{"brew_id":{"type":"string"},"name":{"type":"string"},"style":{"type":"string"},"abv_pct":{"type":"number"},"ibu":{"type":"number"},"last_brewed":{"type":"string","description":"YYYY-MM-DD"},"brewed_by":{"type":"integer","description":"Other brewers who brewed a copy."},"cheers":{"type":"integer"},"share_token":{"type":"string","description":"Pass to adopt_shared_recipe to copy the recipe."}},"required":["brew_id","name","brewed_by","cheers","share_token"]},"description":"Most recently added to the profile first; last_brewed says when each was brewed."},"recent_activity":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["brewed","packaged","listed","milestone"],"description":"brewed, packaged, listed (recipe added to the profile) or milestone (every 10th brew)."},"date":{"type":"string","description":"YYYY-MM-DD"},"brewer":{"type":"object","properties":{"handle":{"type":"string","description":"Pass to get_brewer_profile or interact_with_brewer."},"name":{"type":"string"},"location":{"type":"string"}},"required":["handle","name"]},"brew_id":{"type":"string","description":"For cheer_brew."},"beer":{"type":"string"},"style":{"type":"string"},"milestone":{"type":"integer","description":"Brew count reached (milestones)."},"share_token":{"type":"string","description":"The recipe is shared: pass to adopt_shared_recipe to copy it."},"based_on":{"type":"string","description":"The brew is a copy of this brewer's shared recipe."},"cheers":{"type":"integer"},"cheered_by_you":{"type":"boolean"}},"required":["kind","date","brewer","brew_id","beer","cheers"]},"description":"Last 30 days, newest first (max 20)."},"settings":{"type":"object","properties":{"handle":{"type":"string"},"handle_saved":{"type":"boolean","description":"false: only a suggestion; saved on the first update_community_profile that opens the profile."},"visibility":{"type":"string","enum":["private","members","public"]},"bio":{"type":"string"},"location":{"type":"string"},"brewing_since":{"type":"integer"},"brewhouse":{"type":"string"},"activity_mode":{"type":"string","enum":["listed","all","none"]},"activity_events":{"type":"object","additionalProperties":{"type":"boolean"},"propertyNames":{"enum":["brewed","packaged","listed","milestone"]}},"notify_recipe_brewed":{"type":"boolean"},"indexable":{"type":"boolean"},"suspended":{"type":"boolean"}},"required":["handle","handle_saved","visibility","bio","location","brewhouse","activity_mode","activity_events","notify_recipe_brewed","indexable"],"description":"Own profile only."},"connections":{"type":"object","properties":{"followers":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","description":"Use as brewer in interact_with_brewer when there is no handle."},"handle":{"type":"string"},"name":{"type":"string"},"since":{"type":"string","description":"YYYY-MM-DD"},"you_follow_them":{"type":"boolean"}},"required":["user_id","name","since"]}},"following":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","description":"Use as brewer in interact_with_brewer when there is no handle."},"handle":{"type":"string"},"name":{"type":"string"},"since":{"type":"string","description":"YYYY-MM-DD"},"you_follow_them":{"type":"boolean"}},"required":["user_id","name","since"]}},"blocked":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string","description":"Use as brewer in interact_with_brewer when there is no handle."},"handle":{"type":"string"},"name":{"type":"string"},"since":{"type":"string","description":"YYYY-MM-DD"},"you_follow_them":{"type":"boolean"}},"required":["user_id","name","since"]}},"truncated":{"type":"boolean"}},"required":["followers","following","blocked"],"description":"Own profile only."},"notices":{"type":"object","properties":{"unread":{"type":"integer"},"items":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["unread","items"],"description":"Own profile only: last 30 days. Mark them read with mark_inbox_read (community_notices: true)."}},"required":["brewer","is_you","followers","following","shared_recipes"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/interact_with_brewer":{"post":{"operationId":"interact_with_brewer","tags":["Actions: Community"],"summary":"Follow, unfollow, block or report a brewer","description":"Change the user's relation to another brewer: follow, unfollow, block (ends follows both ways), unblock, remove_follower (they stop following the user), or report (to the BrewForge team). Example: { \"brewer\": \"hopfenhans\", \"action\": \"follow\" }. Following needs the brewer's profile to be open. Reporting sends the user's complaint to the team: confirm the reason and wording with the user first and never report on your own initiative. Repeating follow/unfollow/block/unblock is harmless.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":true},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brewer":{"type":"string","description":"The brewer: their handle (with or without @, e.g. \"hopfenhans\") as shown by browse_community or get_brewer_profile, or their user id from a connections list."},"action":{"type":"string","enum":["follow","unfollow","block","unblock","remove_follower","report"],"description":"What to do."},"report_reason":{"type":"string","enum":["spam","copied","offensive","impersonation","other"],"description":"report only (required): spam, copied (copied someone's recipe), offensive, impersonation or other."},"report_details":{"type":"string","maxLength":1000,"description":"report only: what is wrong, in the user's words (max 1000 characters)."},"report_brew_id":{"type":"string","description":"report only: brew_id of the shared recipe the report is about, if any."}},"required":["brewer","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brewer":{"type":"object","properties":{"user_id":{"type":"string"},"handle":{"type":"string"},"name":{"type":"string"}},"required":["user_id","name"]},"action":{"type":"string","enum":["follow","unfollow","block","unblock","remove_follower","report"]},"message":{"type":"string"}},"required":["brewer","action","message"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/cheer_brew":{"post":{"operationId":"cheer_brew","tags":["Actions: Community"],"summary":"Cheer another brewer's beer","description":"Give (or take back) a Cheers on another brewer's beer, like the 🍻 button in the community feed. Example: { \"brew_id\": \"<brew_id from browse_community>\" }. brew_id comes from browse_community entries/recipes or get_brewer_profile. Pass cheered: false to take a Cheers back. Calling twice with the same value changes nothing.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":true},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brew_id":{"type":"string","description":"brew_id of another brewer's beer, from browse_community or get_brewer_profile."},"cheered":{"type":"boolean","description":"true (default) to cheer, false to take the Cheers back."}},"required":["brew_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew_id":{"type":"string"},"beer":{"type":"string"},"cheered":{"type":"boolean"},"cheers":{"type":"integer","description":"Total Cheers on this beer now."}},"required":["brew_id","beer","cheered","cheers"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/update_community_profile":{"post":{"operationId":"update_community_profile","tags":["Actions: Community"],"summary":"Update the community profile and shared recipes","description":"Change the user's community profile: handle, who can see it (visibility), bio, location, brewing since, brewhouse, which activity is shown, notifications; list recipes on the profile (list_brews: other brewers can see and copy them) or take them off (unlist_brews), and hide single activity entries. Only the fields you pass change. Example: { \"visibility\": \"members\", \"bio\": \"Lager nerd from Franconia\", \"list_brews\": [\"#12\"] }. Making the profile or a recipe visible is public-facing: do it only when the user asked. Listing needs a visible profile (visibility members or public). Read the current settings with get_brewer_profile (no brewer).\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":true},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","description":"Public handle (username), 3-30 letters, digits, _ or ., e.g. \"hopfenhans\". Unique across BrewForge."},"visibility":{"type":"string","enum":["private","members","public"],"description":"private (only the user), members (signed-in BrewForge brewers) or public (anyone with the link)."},"bio":{"type":"string","maxLength":400,"description":"Short bio, max 400 characters. Empty string clears it."},"location":{"type":"string","maxLength":80,"description":"e.g. \"Bamberg, Germany\". Empty string clears it."},"brewing_since":{"type":"integer","minimum":1900,"description":"Year the user started brewing, e.g. 2016."},"brewhouse":{"type":"string","maxLength":80,"description":"Name of the brewery/system, e.g. \"Braumeister 20L\". Empty string clears it."},"activity_mode":{"type":"string","enum":["listed","all","none"],"description":"Which activity followers see: all (every brew), listed (only brews whose recipe is on the profile) or none."},"activity_events":{"type":"object","properties":{"brewed":{"type":"boolean","description":"Show brew days."},"packaged":{"type":"boolean","description":"Show packaging (kegged/bottled)."},"listed":{"type":"boolean","description":"Show recipes added to the profile."},"milestone":{"type":"boolean","description":"Show every 10th brew."}},"additionalProperties":false,"description":"Turn single kinds of activity on/off, e.g. { \"packaged\": false }."},"notify_recipe_brewed":{"type":"boolean","description":"Notify the user when someone brews a copy of their shared recipe."},"indexable":{"type":"boolean","description":"Let search engines index the profile (public profiles only)."},"list_brews":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Brews whose recipe to show on the profile. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"unlist_brews":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Brews whose recipe to take off the profile (its share link keeps working). The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"hide_activity":{"type":"array","items":{"type":"object","properties":{"brew":{"type":"string","description":"The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"kind":{"type":"string","enum":["brewed","packaged","listed","milestone"],"description":"Which entry of that brew: brewed, packaged, listed or milestone."}},"required":["brew","kind"],"additionalProperties":false},"maxItems":50,"description":"Activity entries of the user's own brews to hide from the feed and profile."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"handle":{"type":"string"},"visibility":{"type":"string","enum":["private","members","public"]},"bio":{"type":"string","description":"Empty string when not set."},"location":{"type":"string","description":"Empty string when not set."},"brewing_since":{"type":"integer"},"brewhouse":{"type":"string","description":"Empty string when not set."},"activity_mode":{"type":"string","enum":["listed","all","none"]},"activity_events":{"type":"object","additionalProperties":{"type":"boolean"},"propertyNames":{"enum":["brewed","packaged","listed","milestone"]}},"notify_recipe_brewed":{"type":"boolean"},"indexable":{"type":"boolean"}},"required":["handle","visibility","bio","location","brewhouse","activity_mode","activity_events","notify_recipe_brewed","indexable"]},"listed":{"type":"array","items":{"type":"object","properties":{"brew_id":{"type":"string"},"name":{"type":"string"},"share_token":{"type":"string"}},"required":["brew_id","name"]}},"unlisted":{"type":"array","items":{"type":"object","properties":{"brew_id":{"type":"string"},"name":{"type":"string"}},"required":["brew_id","name"]}},"hidden_activity":{"type":"array","items":{"type":"object","properties":{"brew_id":{"type":"string"},"kind":{"type":"string","enum":["brewed","packaged","listed","milestone"]}},"required":["brew_id","kind"]}}},"required":["settings"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/adopt_shared_recipe":{"post":{"operationId":"adopt_shared_recipe","tags":["Actions: Community"],"summary":"Copy a shared recipe into the user's brews","description":"Save a recipe another brewer shared (share link or share_token from browse_community / get_brewer_profile) as a new brew idea in the user's own recipe book, like \"Save to my recipes\" on the share page. Example: { \"share\": \"https://brewforge.sh/share/3f9a1c2b4d5e6f70\" } or { \"share\": \"3f9a1c2b4d5e6f70\" }. Counts against the plan's brew limit. Returns the new brew's id; continue with the brewing tools (e.g. get_brew).\n\nScope: `brews:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"brews:write","area":"brews","idempotent":false},"security":[{"bearerAuth":["brews:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"share":{"type":"string","description":"The share link (\".../share/<token>\") or just the share token."}},"required":["share"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"brew":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"]},"based_on":{"type":"object","properties":{"name":{"type":"string"},"brewer":{"type":"string"}},"required":["name","brewer"]}},"required":["brew","based_on"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/find_feedback_threads":{"post":{"operationId":"find_feedback_threads","tags":["Actions: Community"],"summary":"Find feedback threads (feature requests, questions, roadmap)","description":"Search BrewForge's public Feedback board (brewforge.sh/feedback): feature requests and questions from all brewers, with votes and status. With query: the threads most similar to the text (full-text, finds rewordings), e.g. { \"query\": \"water chemistry per mash step\" }. ALWAYS search like this before post_feedback to avoid duplicates; results are the closest threads, not necessarily the same request, so compare titles (and read a thread when unsure). roadmap: true lists the feature requests on the roadmap (under_review, planned, in_progress, shipped); for what is coming next add status: [\"planned\", \"in_progress\"]. mine: \"voted\" / \"commented\" lists the user's own. Then get_feedback_thread for the full thread, react_to_feedback to vote.\n\nScope: `community:read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"community:read","area":"community","idempotent":true},"security":[{"bearerAuth":["community:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"What the thread is about, in plain words (at least 4 characters), e.g. \"export to BeerXML\". Ranked by similarity; max 10 results, no paging."},"category":{"type":"string","enum":["feature","question"],"description":"feature (feature requests) or question."},"status":{"type":"array","items":{"type":"string","enum":["open","under_review","planned","in_progress","shipped","declined","answered","closed","merged"]},"description":"Only these statuses, e.g. [\"planned\", \"in_progress\"]. Features: open, under_review, planned, in_progress, shipped, declined. Questions: open, answered, closed."},"roadmap":{"type":"boolean","description":"Only feature requests on the roadmap board (under_review, planned, in_progress, shipped), most voted first."},"mine":{"type":"string","enum":["voted","commented"],"description":"Only threads the user upvoted or posted in."},"input_wanted":{"type":"boolean","description":"Only threads with an open questionnaire the user has not answered yet."},"sort":{"type":"string","enum":["top","trending","new","active"],"description":"Without query: top (most votes, default), trending (votes in the last weeks), new, or active (latest activity)."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"How many rows to return, 1-100 (default 20)."},"cursor":{"type":"string","description":"next_cursor from the previous page, to get the next page. Omit for the first page."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","description":"Thread number: pass as thread to the other feedback tools."},"title":{"type":"string"},"category":{"type":"string","enum":["feature","question"]},"status":{"type":"string","enum":["open","under_review","planned","in_progress","shipped","declined","answered","closed","merged"]},"votes":{"type":"integer","description":"Upvotes (feature requests)."},"you_voted":{"type":"boolean"},"replies":{"type":"integer"},"summary":{"type":"string","description":"Short excerpt of the curated summary."},"labels":{"type":"array","items":{"type":"string"}},"your_input_wanted":{"type":"boolean","description":"A questionnaire is open that the user has not answered (answer_feedback_questionnaire)."},"author":{"type":"string"},"last_activity":{"type":"string","description":"YYYY-MM-DD"},"url":{"type":"string"}},"required":["number","title","category","status","url"]}},"next_cursor":{"type":["string","null"],"description":"Pass as cursor to get the next page; null on the last page."},"total":{"type":"integer","description":"Matching threads in all pages (without query)."},"note":{"type":"string"}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_feedback_thread":{"post":{"operationId":"get_feedback_thread","tags":["Actions: Community"],"summary":"Read a feedback thread","description":"One Feedback thread with its status, votes, the original post, replies (10 per page, newest last), the team's summary and brief, open questionnaires and what the user may do (vote, reply). Example: { \"thread\": 33 }. Long posts are cut; pass full_post_id to get one post in full. Use the post ids with react_to_feedback / edit_feedback_post / delete_feedback_post, and questionnaire ids with answer_feedback_questionnaire.\n\nScope: `community:read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"community:read","area":"community","idempotent":true},"security":[{"bearerAuth":["community:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"The feedback thread: its number (33, \"#33\") or its URL (e.g. \"https://brewforge.sh/feedback/33-water-per-mash-step\"). Find numbers with find_feedback_threads."},"full_post_id":{"type":"string","description":"Return only this post, uncut (original post or reply id from a previous call)."},"replies_limit":{"type":"integer","minimum":0,"maximum":50,"description":"Replies per page, 0-50 (default 10)."},"cursor":{"type":"string","description":"next_replies_cursor from the previous call, for more replies."}},"required":["thread"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"integer"},"title":{"type":"string"},"category":{"type":"string","enum":["feature","question"]},"status":{"type":"string","enum":["open","under_review","planned","in_progress","shipped","declined","answered","closed","merged"]},"status_reason":{"type":"string","description":"The team's public reason for the status."},"url":{"type":"string"},"author":{"type":"string"},"created":{"type":"string"},"votes":{"type":"integer"},"labels":{"type":"array","items":{"type":"string"}},"summary":{"type":"string","description":"Curated summary (Markdown)."},"brief":{"type":"string","description":"\"How this could work\" from the team (Markdown, cut at 1500 characters)."},"merged_into":{"type":"integer","description":"This thread was merged: read and post in that thread instead."},"you":{"type":"object","properties":{"voted":{"type":"boolean"},"vote_state":{"type":"string","enum":["voted","eligible","upgrade","closed","not_votable"],"description":"eligible: can upvote; upgrade: needs a paid plan; closed: voting over; not_votable: questions."},"subscribed":{"type":"boolean","description":"Gets in-app notifications for this thread."},"is_author":{"type":"boolean"},"can_reply":{"type":"boolean"},"reply_blocked_because":{"type":"string"},"can_accept_answer":{"type":"boolean","description":"Question author: may mark a reply as the accepted answer."}},"required":["vote_state","subscribed","is_author","can_reply"]},"original_post":{"type":"object","properties":{"id":{"type":"string","description":"Post id: for edit_feedback_post, delete_feedback_post, react_to_feedback (reply_vote, accept_answer, report)."},"author":{"type":"string"},"body":{"type":"string","description":"Markdown; cut at 500 characters (1500 for the original post) when truncated is true: pass the id as full_post_id for all of it."},"truncated":{"type":"boolean"},"date":{"type":"string","description":"YYYY-MM-DD"},"score":{"type":"integer","description":"Reply votes (up minus down)."},"your_vote":{"type":"integer","description":"1 or -1 when the user voted on this reply."},"yours":{"type":"boolean"},"accepted_answer":{"type":"boolean"},"edited":{"type":"boolean"},"deleted":{"type":"boolean"},"moderation":{"type":"string","description":"Own posts only: held (waiting for review, not public yet) or rejected, with the reason."},"collapsed":{"type":"boolean","description":"Low score; hidden by default in the app."},"from_thread":{"type":"integer","description":"Posted in a thread that was merged into this one."}},"required":["id","author","body","date"]},"accepted_answer":{"type":"object","properties":{"id":{"type":"string","description":"Post id: for edit_feedback_post, delete_feedback_post, react_to_feedback (reply_vote, accept_answer, report)."},"author":{"type":"string"},"body":{"type":"string","description":"Markdown; cut at 500 characters (1500 for the original post) when truncated is true: pass the id as full_post_id for all of it."},"truncated":{"type":"boolean"},"date":{"type":"string","description":"YYYY-MM-DD"},"score":{"type":"integer","description":"Reply votes (up minus down)."},"your_vote":{"type":"integer","description":"1 or -1 when the user voted on this reply."},"yours":{"type":"boolean"},"accepted_answer":{"type":"boolean"},"edited":{"type":"boolean"},"deleted":{"type":"boolean"},"moderation":{"type":"string","description":"Own posts only: held (waiting for review, not public yet) or rejected, with the reason."},"collapsed":{"type":"boolean","description":"Low score; hidden by default in the app."},"from_thread":{"type":"integer","description":"Posted in a thread that was merged into this one."}},"required":["id","author","body","date"]},"replies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Post id: for edit_feedback_post, delete_feedback_post, react_to_feedback (reply_vote, accept_answer, report)."},"author":{"type":"string"},"body":{"type":"string","description":"Markdown; cut at 500 characters (1500 for the original post) when truncated is true: pass the id as full_post_id for all of it."},"truncated":{"type":"boolean"},"date":{"type":"string","description":"YYYY-MM-DD"},"score":{"type":"integer","description":"Reply votes (up minus down)."},"your_vote":{"type":"integer","description":"1 or -1 when the user voted on this reply."},"yours":{"type":"boolean"},"accepted_answer":{"type":"boolean"},"edited":{"type":"boolean"},"deleted":{"type":"boolean"},"moderation":{"type":"string","description":"Own posts only: held (waiting for review, not public yet) or rejected, with the reason."},"collapsed":{"type":"boolean","description":"Low score; hidden by default in the app."},"from_thread":{"type":"integer","description":"Posted in a thread that was merged into this one."}},"required":["id","author","body","date"]}},"replies_total":{"type":"integer"},"next_replies_cursor":{"type":["string","null"]},"questionnaires":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["live","closed"]},"title":{"type":"string"},"intro":{"type":"string"},"respondents":{"type":"integer"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"multiple":{"type":"boolean","description":"Several options may be picked."},"allow_other":{"type":"boolean","description":"Free-text \"other\" answer allowed."},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"share_pct":{"type":"number"}},"required":["id","label"]}},"other_pct":{"type":"number"},"your_answer":{"type":"object","properties":{"option_ids":{"type":"array","items":{"type":"string"}},"other":{"type":"string"}},"required":["option_ids"]}},"required":["id","text","multiple","allow_other","options"]}},"you_answered":{"type":"boolean"}},"required":["id","status","title","respondents","questions","you_answered"]}},"related":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"thread":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"}},"required":["type"]}},"post":{"type":"object","properties":{"id":{"type":"string","description":"Post id: for edit_feedback_post, delete_feedback_post, react_to_feedback (reply_vote, accept_answer, report)."},"author":{"type":"string"},"body":{"type":"string","description":"Markdown; cut at 500 characters (1500 for the original post) when truncated is true: pass the id as full_post_id for all of it."},"truncated":{"type":"boolean"},"date":{"type":"string","description":"YYYY-MM-DD"},"score":{"type":"integer","description":"Reply votes (up minus down)."},"your_vote":{"type":"integer","description":"1 or -1 when the user voted on this reply."},"yours":{"type":"boolean"},"accepted_answer":{"type":"boolean"},"edited":{"type":"boolean"},"deleted":{"type":"boolean"},"moderation":{"type":"string","description":"Own posts only: held (waiting for review, not public yet) or rejected, with the reason."},"collapsed":{"type":"boolean","description":"Low score; hidden by default in the app."},"from_thread":{"type":"integer","description":"Posted in a thread that was merged into this one."}},"required":["id","author","body","date"],"description":"Only with full_post_id: that post, uncut."}},"required":["number","title","category","status","url","author","created","you","replies","replies_total","next_replies_cursor"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/post_feedback":{"post":{"operationId":"post_feedback","tags":["Actions: Community"],"summary":"Post a feature request, question or reply in Feedback","description":"Write in BrewForge's public Feedback board under the user's public username. PUBLIC: show the user the exact title and text and get their OK before calling; never post on your own initiative. New thread: category (\"feature\" or \"question\"), title and body. The tool first checks for similar existing threads: when it finds some it does NOT post and returns them, so you can vote there instead (react_to_feedback) or call again with skip_duplicate_check: true if the user still wants a new thread. Reply: pass thread (number) and body, e.g. { \"thread\": 33, \"body\": \"+1, I need this for decoction mashes.\" }. Posting limits: accounts younger than 7 days cannot post; free plan 3 threads / 10 replies per month, paid plans 3 threads / 30 replies per day.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":false},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"Reply to this thread. The feedback thread: its number (33, \"#33\") or its URL (e.g. \"https://brewforge.sh/feedback/33-water-per-mash-step\"). Find numbers with find_feedback_threads. Omit to start a new thread."},"category":{"type":"string","enum":["feature","question"],"description":"New thread only (required): feature (feature request) or question."},"title":{"type":"string","maxLength":140,"description":"New thread only (required): 8-140 characters, e.g. \"Water chemistry per mash step\"."},"body":{"type":"string","maxLength":10000,"description":"The text (Markdown), 1-10000 characters, in the user's words."},"handle":{"type":"string","maxLength":30,"description":"Only needed for the user's very first post when they have no public handle (username) yet (the error says so): 3-30 letters, digits, _ or .. Ask the user."},"skip_duplicate_check":{"type":"boolean","description":"New thread only: post even though similar threads exist (after the user saw them)."}},"required":["body"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"posted":{"type":"boolean"},"thread":{"type":"integer","description":"Thread number."},"url":{"type":"string"},"reply_id":{"type":"string"},"moderation":{"type":"string","enum":["published","held","rejected"]},"moderation_reason":{"type":"string"},"similar_threads":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string"},"votes":{"type":"integer"},"you_voted":{"type":"boolean"},"url":{"type":"string"}},"required":["number","title","status","url"]},"description":"Not posted: these threads look like the same request."},"message":{"type":"string"}},"required":["posted","message"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/edit_feedback_post":{"post":{"operationId":"edit_feedback_post","tags":["Actions: Community"],"summary":"Edit the user's own Feedback post","description":"Change the text of one of the user's own posts in Feedback (a thread's original post or a reply). Thread titles are curated by the team once a thread is published; only a held thread's title can still change. Get post ids from get_feedback_thread (original_post.id, replies[].id where yours is true). Example: { \"post_id\": \"abc123\", \"body\": \"Updated: also for step mashes.\" }. PUBLIC: confirm the new text with the user first. The edit is checked like a new post and may wait for review before it shows.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":true},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string","description":"Id of the user's own post (original_post.id or a reply id from get_feedback_thread)."},"body":{"type":"string","maxLength":10000,"description":"The complete new text (Markdown), 1-10000 characters. Replaces the old text."},"title":{"type":"string","maxLength":140,"description":"Original post of a thread still held for review only: new title, 8-140 characters."}},"required":["post_id","body"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string"},"applied":{"type":"boolean","description":"true: the new text shows now; false: it waits for review (the old text stays until then)."},"moderation":{"type":"string","enum":["published","held","rejected"]},"moderation_reason":{"type":"string"}},"required":["post_id","applied","moderation"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/delete_feedback_post":{"post":{"operationId":"delete_feedback_post","tags":["Actions: Community"],"summary":"Delete the user's own Feedback post","description":"Delete one of the user's own Feedback posts (a reply, or the original post of their thread). It then shows as \"deleted by the author\"; votes and other replies stay. Without confirm: true it only shows which post would be deleted. Only when the user asked for it.\n\nDestructive: without `confirm: true` nothing changes and the response is `{ needs_confirmation: true, would_delete, message }`. Scope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"destructive","required_scope":"community:write","area":"community","idempotent":false},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string","description":"Id of the user's own post, from get_feedback_thread (original_post.id or replies[].id with yours: true)."},"confirm":{"type":"boolean","description":"Set to true to really do it. Without it nothing changes and the result lists what would be removed."}},"required":["post_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/react_to_feedback":{"post":{"operationId":"react_to_feedback","tags":["Actions: Community"],"summary":"Vote, follow, accept an answer or report in Feedback","description":"Everything except writing posts, in one call: upvote a feature request ({ \"thread\": 33, \"vote\": true }; false removes the vote), follow a thread for notifications (subscribe), vote on a reply (reply_id + reply_vote 1 / -1 / 0), mark a reply as the accepted answer of the user's own question (accept_answer_post_id), suggest that the thread duplicates another (duplicate_of), or report a post to the moderators (report_post_id + report_reason). Pass only what you want to change. Voting on feature requests needs a paid plan (Basic+). Reports and duplicate suggestions go to the team: only when the user asked.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":true},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"The feedback thread: its number (33, \"#33\") or its URL (e.g. \"https://brewforge.sh/feedback/33-water-per-mash-step\"). Find numbers with find_feedback_threads. Needed for vote, subscribe, accept_answer_post_id and duplicate_of."},"vote":{"type":"boolean","description":"Feature requests: true upvotes, false removes the upvote."},"subscribe":{"type":"boolean","description":"true: in-app notifications for new replies and status changes; false: stop them."},"reply_id":{"type":"string","description":"Reply to vote on (id from get_feedback_thread); use with reply_vote."},"reply_vote":{"type":"number","enum":[1,-1,0],"description":"1 helpful, -1 not helpful, 0 removes the user's vote."},"accept_answer_post_id":{"type":"string","description":"The user's own question only: reply id to mark as the accepted answer, or \"none\" to unmark."},"duplicate_of":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"Number of the older thread this one duplicates (a suggestion for the team)."},"duplicate_note":{"type":"string","maxLength":500,"description":"Why they are duplicates (optional)."},"report_post_id":{"type":"string","description":"Post to report to the moderators (id from get_feedback_thread)."},"report_reason":{"type":"string","enum":["insult","hate","sexual","spam","personal_data","off_topic","other"],"description":"With report_post_id (required): insult, hate, sexual, spam, personal_data, off_topic or other."},"report_details":{"type":"string","maxLength":1000,"description":"With report_post_id: what is wrong (optional)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"type":"integer"},"voted":{"type":"boolean"},"subscribed":{"type":"boolean"},"reply_vote":{"type":"integer"},"accepted_answer":{"type":"string","description":"Post id now accepted, or \"none\"."},"duplicate_suggested":{"type":"integer"},"reported":{"type":"object","properties":{"post_id":{"type":"string"},"hidden":{"type":"boolean","description":"The post is hidden until a moderator looks at it."}},"required":["post_id","hidden"]}}}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/answer_feedback_questionnaire":{"post":{"operationId":"answer_feedback_questionnaire","tags":["Actions: Community"],"summary":"Answer a feedback questionnaire","description":"Submit (or change) the user's answers to the open questionnaire of a feature request, which the BrewForge team uses to decide how to build it. First read the questions and option ids with get_feedback_thread (questionnaires[]), ask the user, then pass one answer per question. Example: { \"thread\": 33, \"answers\": [{ \"question_id\": \"q1\", \"option_ids\": [\"per-step\"] }, { \"question_id\": \"q2\", \"option_ids\": [], \"other\": \"only for decoction\" }] }. Every question needs an answer; single-choice questions take exactly one option (or other). The result shows the totals so far.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":true},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"The feedback thread: its number (33, \"#33\") or its URL (e.g. \"https://brewforge.sh/feedback/33-water-per-mash-step\"). Find numbers with find_feedback_threads."},"questionnaire_id":{"type":"string","description":"Questionnaire id from get_feedback_thread; default: the thread's open questionnaire."},"answers":{"type":"array","items":{"type":"object","properties":{"question_id":{"type":"string","description":"Question id, e.g. \"q1\"."},"option_ids":{"type":"array","items":{"type":"string"},"description":"Picked option ids, e.g. [\"per-step\"]; [] when only other is given."},"other":{"type":"string","maxLength":500,"description":"Free-text \"other\" answer (only where allow_other is true)."}},"required":["question_id","option_ids"],"additionalProperties":false},"minItems":1,"description":"One entry per question."}},"required":["thread","answers"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"thread":{"type":"integer"},"questionnaire_id":{"type":"string"},"saved":{"type":"boolean"},"moderation":{"type":"string","enum":["published","held","rejected"],"description":"Of the \"other\" texts (published when there are none)."},"message":{"type":"string"}},"required":["thread","questionnaire_id","saved","moderation","message"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/contact_support":{"post":{"operationId":"contact_support","tags":["Actions: Community"],"summary":"Report a problem to support, or reply on a ticket","description":"Support tickets are for bugs: something in BrewForge is broken or wrong. Feature wishes go to Feedback (post_feedback), questions on how to use BrewForge too. New bug report: title, details, severity, e.g. { \"title\": \"Brew day timer stops when the phone locks\", \"details\": \"Steps: ...\", \"severity\": \"medium\" }. Reply on an existing ticket: ticket + message, e.g. { \"ticket\": 412, \"message\": \"It happens on Android too.\" }. The BrewForge team reads every ticket and answers in the inbox (get_inbox). Confirm the text with the user before sending. Limit: 5 reports per hour, 10 per day. Screenshots can't be attached here; the user can add them in the app.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":false},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ticket":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"Reply on this ticket. The support ticket: its number (412 or \"#412\") or id, from get_inbox. Omit to report a new problem."},"message":{"type":"string","maxLength":5000,"description":"Reply only (required): the user's answer to the team."},"title":{"type":"string","maxLength":200,"description":"New report (required): what the user was trying to do / what broke, max 200 characters, e.g. \"Brew day timer stops when the phone locks\"."},"details":{"type":"string","maxLength":2000,"description":"New report: steps to reproduce, what was expected, what happened (max 2000 characters)."},"severity":{"type":"string","enum":["minor","medium","blocking"],"description":"New report: minor (cosmetic), medium (default; something doesn't work) or blocking (can't continue)."},"page":{"type":"string","maxLength":500,"description":"New report: where in BrewForge it happens, a URL path or screen name, e.g. \"/brews/123\" or \"brew day timer\"."},"brew":{"type":"string","description":"New report: the brew it is about, if any. The brew: its id, its batch number (e.g. 12 or \"#12\") or its exact name (e.g. \"Citra Pale Ale\"). Case does not matter."},"not_a_feature_request":{"type":"boolean","description":"New report: set true when the first call said it looks like a feature request but the user confirms it is a bug."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["created","replied","looks_like_feature_request"]},"ticket":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer"},"status":{"type":"string"}},"required":["id"]},"message":{"type":"string"}},"required":["status","message"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_inbox":{"post":{"operationId":"get_inbox","tags":["Actions: Community"],"summary":"Inbox: support tickets, team messages and notifications","description":"The user's inbox: how many things need attention, their support tickets (open by default) with unread team replies, messages from the BrewForge team, Feedback notifications (replies and status changes on followed threads) and community notices (new followers, cheers). Answers \"did support answer my ticket?\". With ticket (e.g. { \"ticket\": 412 }): that ticket with the whole conversation. Reading does not mark anything as read; use mark_inbox_read for that, and contact_support to reply on a ticket.\n\nScope: `community:read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"community:read","area":"community","idempotent":true},"security":[{"bearerAuth":["community:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ticket":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"Show this ticket with its messages. The support ticket: its number (412 or \"#412\") or id, from get_inbox."},"tickets":{"type":"string","enum":["open","closed","all"],"description":"Which tickets to list (default open)."},"include":{"type":"array","items":{"type":"string","enum":["tickets","messages","feedback","community"]},"description":"Sections to return (default all): tickets, messages (from the team), feedback (notifications), community (notices)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"needs_attention":{"type":"integer","description":"Unread team messages plus tickets with an unread reply or waiting for the user (the app's inbox badge)."},"tickets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","description":"Ticket number: pass it (e.g. 412) as ticket to get_inbox, contact_support or mark_inbox_read; the id works too."},"title":{"type":"string"},"status":{"type":"string","description":"reopened = the user wrote again after the team answered or closed it. Others: new, acked, in_progress, waiting_customer (the team waits for the user's answer), resolved, wontfix, reopened, added_to_external."},"severity":{"type":"string"},"unread_reply":{"type":"boolean","description":"The team answered and the user has not read it."},"bounty_points":{"type":"integer"},"milestone":{"type":"string"},"last_activity":{"type":"string"}},"required":["id","title","status"]}},"messages":{"type":"object","properties":{"unread":{"type":"integer"},"archived":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"truncated":{"type":"boolean"},"read":{"type":"boolean"},"date":{"type":"string"},"from":{"type":"string"}},"required":["id","subject","body","read","date"]}}},"required":["unread","archived","items"],"description":"Messages from the team that belong to no ticket, newest first (archived ones left out)."},"feedback_notifications":{"type":"object","properties":{"unread":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"read":{"type":"boolean"},"date":{"type":"string"},"thread":{"type":"integer"},"title":{"type":"string"},"by":{"type":"string"},"new_status":{"type":"string"},"url":{"type":"string"}},"required":["id","type","read","date"]}}},"required":["unread","items"]},"community_notices":{"type":"object","properties":{"unread":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"date":{"type":"string"},"by":{"type":"string"},"beer":{"type":"string"},"count":{"type":"integer"}},"required":["kind","date","by"]}}},"required":["unread","items"]},"ticket":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","description":"Ticket number: pass it (e.g. 412) as ticket to get_inbox, contact_support or mark_inbox_read; the id works too."},"title":{"type":"string"},"status":{"type":"string","description":"reopened = the user wrote again after the team answered or closed it. Others: new, acked, in_progress, waiting_customer (the team waits for the user's answer), resolved, wontfix, reopened, added_to_external."},"severity":{"type":"string"},"unread_reply":{"type":"boolean","description":"The team answered and the user has not read it."},"bounty_points":{"type":"integer"},"milestone":{"type":"string"},"last_activity":{"type":"string"},"team_replied":{"type":"boolean","description":"Whether any message in the conversation is from the team."},"details":{"type":"string"},"page":{"type":"string"},"created":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","enum":["you","team"]},"name":{"type":"string"},"body":{"type":"string"},"truncated":{"type":"boolean"},"date":{"type":"string"},"attachments":{"type":"integer"}},"required":["from","body","date"]}}},"required":["id","title","status","team_replied","created","messages"],"description":"Only with ticket: the ticket and its conversation, oldest first."}}}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/mark_inbox_read":{"post":{"operationId":"mark_inbox_read","tags":["Actions: Community"],"summary":"Mark inbox items as read or archive messages","description":"Mark things in the user's inbox as read, like opening them in the app: team messages (by id, or all), a ticket's replies, Feedback notifications (by id, or all) and community notices; archive team messages. Pass only what to change. Example: { \"ticket\": 412, \"all_feedback_notifications\": true }. Ids come from get_inbox. Only do this when the user has seen the items or asked for it.\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":true},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_ids":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Team message ids (get_inbox messages.items[].id) to mark read."},"all_messages":{"type":"boolean","description":"true: mark every team message and ticket reply as read."},"archive_message_ids":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Team message ids to archive (hidden from the inbox, not deleted)."},"ticket":{"anyOf":[{"type":"integer"},{"type":"string"}],"description":"Mark this ticket's team replies as read. The support ticket: its number (412 or \"#412\") or id, from get_inbox."},"feedback_notification_ids":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Feedback notification ids (get_inbox feedback_notifications.items[].id)."},"all_feedback_notifications":{"type":"boolean","description":"true: mark every Feedback notification read."},"community_notices":{"type":"boolean","description":"true: mark the community notices (follows, cheers) as seen."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"marked_read":{"type":"integer","description":"Team messages marked read by id."},"archived":{"type":"integer"},"ticket":{"type":"integer"},"feedback_unread":{"type":"integer","description":"Unread Feedback notifications left."},"community_notices_seen":{"type":"boolean"},"needs_attention":{"type":"integer","description":"Inbox badge count after the change."}},"required":["needs_attention"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_changelog":{"post":{"operationId":"get_changelog","tags":["Actions: Community"],"summary":"What's new in BrewForge","description":"BrewForge's changelog: new features and bug fixes, newest first. Answers \"what's new in BrewForge this month?\" ({ \"since\": \"2026-11-01\" }) or \"was the timer bug fixed?\" ({ \"query\": \"timer\" }). Entries are one-line English descriptions with a date.\n\nScope: `community:read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"community:read","area":"community","idempotent":true},"security":[{"bearerAuth":["community:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","description":"Only entries on or after this day, YYYY-MM-DD, e.g. \"2026-11-01\"."},"type":{"type":"string","enum":["feature","bug","all"],"description":"feature (new features), bug (fixes) or all (default)."},"query":{"type":"string","maxLength":100,"description":"Only entries whose text contains this (case-insensitive), e.g. \"cellar\"."},"limit":{"type":"integer","minimum":1,"maximum":200,"description":"Max entries (default 30)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"type":{"type":"string","enum":["feature","bug"]},"text":{"type":"string"}},"required":["date","type","text"]}},"total":{"type":"integer","description":"Matching entries before limit."},"features":{"type":"integer"},"fixes":{"type":"integer"},"note":{"type":"string","description":"Present when more entries match than were returned."}},"required":["entries","total","features","fixes"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/get_account_overview":{"post":{"operationId":"get_account_overview","tags":["Actions: Community"],"summary":"Plan, limits, bounty points and referrals","description":"The user's BrewForge plan (name; renews_on or ends_on for a paid subscription, else period_note says why there is no date), brew limit and usage, which plan features are on, the bounty point balance (points from bug reports, codes and referrals, worth discounts) and the referral link with its stats. Read only: plan changes, checkout and discounts happen in the app (brewforge.sh/subscriptions, /bounty). include: [\"bounty_history\"] adds the last point transactions.\n\nScope: `community:read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"community:read","area":"community","idempotent":true},"security":[{"bearerAuth":["community:read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","enum":["bounty_history","referrals"]},"description":"Extra sections: bounty_history (last 50 point transactions)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","description":"Subscription status, e.g. active, trialing, canceled."},"renews_on":{"type":"string","description":"YYYY-MM-DD the paid subscription renews."},"ends_on":{"type":"string","description":"YYYY-MM-DD the plan ends (subscription cancelled at the end of its period)."},"ends_at_period_end":{"type":"boolean"},"period_note":{"type":"string","description":"Why there is no renewal or end date, when there is none."}},"required":["name"]},"brews":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer","description":"Max brews on this plan; missing when unlimited."},"unlimited":{"type":"boolean","description":"True when the plan has no brew limit."},"locked":{"type":"integer","description":"Brews over the limit that are read-only."}},"required":["used"]},"features":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"}},"not_enabled":{"type":"array","items":{"type":"string"}}},"required":["enabled","not_enabled"]},"bounty":{"type":"object","properties":{"points":{"type":"integer","description":"Balance; 1 point = 10 % off a Basic or Pro subscription (up to 10 points at once), redeemed in the app."},"history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"points":{"type":"integer"},"type":{"type":"string"},"reason":{"type":"string"},"ticket":{"type":"string"}},"required":["date","points","type"]}}},"required":["points"]},"referral":{"type":"object","properties":{"link":{"type":"string","description":"Share this link; signups through it earn points when they subscribe."},"signups":{"type":"integer"},"paid_conversions":{"type":"integer"},"points_earned":{"type":"integer"}},"required":["link","signups","paid_conversions","points_earned"]}},"required":["plan","brews","features","bounty","referral"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/redeem_bounty_code":{"post":{"operationId":"redeem_bounty_code","tags":["Actions: Community"],"summary":"Redeem a bounty code","description":"Redeem a printed or emailed BrewForge bounty code (e.g. from a beer festival card) for bounty points. Example: { \"code\": \"K7MX9PQR\" }. Each code works once per user. Returns the points gained and the new balance; spending points on a discount happens in the app (/bounty).\n\nScope: `community:write` (or `write`).","x-brewforge-action":{"toolset":"community","access":"write","required_scope":"community:write","area":"community","idempotent":false},"security":[{"bearerAuth":["community:write"]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":4,"maxLength":40,"description":"The code as printed, e.g. \"K7MX-9PQR\" or \"k7mx9pqr\" (case and dashes do not matter)."}},"required":["code"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"points_added":{"type":"integer"},"balance":{"type":"integer"}},"required":["points_added","balance"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/actions/export_my_data":{"post":{"operationId":"export_my_data","tags":["Actions: Community"],"summary":"Export the user's account data (JSON)","description":"The full data export of the account (the same JSON as Settings → Account → Export data), in pieces because it can be several MB. Without section: the export's sections with how many records each holds. Then ask for one section at a time, e.g. { \"section\": \"profiles\" }; list sections (brews, messages, bjcpEvaluations, ...) come in pages: { \"section\": \"brews\", \"limit\": 5, \"cursor\": \"...\" }. Raw records with internal field names; for working with brews prefer the brewing tools. Use this for backups or when the user asks for their data. Needs a token with the full \"read\" scope.\n\nScope: `read` (or `read`).","x-brewforge-action":{"toolset":"community","access":"read","required_scope":"read","area":"settings","idempotent":true},"security":[{"bearerAuth":["read"]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"section":{"type":"string","enum":["user","subscription","preferences","brews","inventory","profiles","orderLists","customFields","devices","cellar","bjcpEvaluations","feedback","bountyTransactions","messages","apiTokens","ingredientSubscriptions","customIngredientPackages","migrationRequests"],"description":"Which part of the export to return. Omit for the overview."},"limit":{"type":"integer","minimum":1,"maximum":50,"description":"List sections: records per page (default 5; brews are large, keep it small)."},"cursor":{"type":"string","description":"next_cursor from the previous page of the same section."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"exported_at":{"type":"string"},"export_version":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"records":{"type":"integer"}},"required":["name","records"]},"description":"Overview only."},"approx_size_kb":{"type":"integer","description":"Overview only: size of the whole export."},"section":{"type":"string"},"data":{"description":"The section's records (a page of them for list sections)."},"total":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["exported_at","export_version"]}}}},"400":{"description":"Invalid input (VALIDATION_ERROR with fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"SCOPE_REQUIRED, TIER_REQUIRED or FORBIDDEN","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"NOT_FOUND (with candidates)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"AMBIGUOUS_REFERENCE (with candidates) or CONFLICT","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"e.g. VALIDATION_ERROR, NOT_FOUND, AMBIGUOUS_REFERENCE, SCOPE_REQUIRED, TIER_REQUIRED"},"message":{"type":"string","description":"What happened and what to do next"},"hint":{"type":"string"},"candidates":{"type":"array","description":"For NOT_FOUND / AMBIGUOUS_REFERENCE: things to retry with (by id)","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Field path → messages"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}}},"webhooks":{}}