List brew batches, newest first by default.

Ordering is by brew date, not by id — Brewfather's default _id ordering is not chronological, so "newest" would otherwise be meaningless.

Args: status: Optional filter. One of Planning, Brewing, Fermenting, Conditioning, Completed, Archived. limit: Maximum batches to return. Default 25. newest_first: Sort by brew date descending. Default True.

Returns: Compact rows: id, batch number, name, style, brew date, status, and measured OG/FG/ABV. Use get_batch for the full record.

Fetch one batch in full, or just the sections you need.

Full batch records are large. Passing sections trims the payload to the parts you actually want.

Args: batch_id: The batch _id from list_batches. sections: Optional subset of: fermentables, hops, yeast, miscs, mash, fermentation, water, measurements, notes. Omit for everything.

Returns: Grain bill with weights and bill percentages, hop schedule with timing and use, yeast and pitch info, mash steps, fermentation schedule, water profile, and all measured values. Weights, volumes and temperatures carry both US customary and metric.

Fetch fermentation readings (Tilt or manual) for a batch.

An active ferment can log thousands of points, so the series is downsampled evenly rather than returned whole. The first and last readings are always kept.

Args: batch_id: The batch _id. latest_only: Return just the most recent reading. Default False. downsample_to: Approximate number of points to return. Default 200. Set to 0 to disable downsampling and return everything.

Returns: The reading series plus a derived summary: first and last gravity, min/max/mean temperature, apparent attenuation, and days elapsed. The summary is always computed over the full series, not the downsampled one.

List saved recipes.

Note: Brewfather has no server-side name search. name_contains filters after fetching, so it costs a full page walk of limit recipes and can return fewer results than limit — raise limit when filtering.

Args: limit: Maximum recipes to fetch before filtering. Default 25. name_contains: Case-insensitive substring filter applied client-side.

Returns: Compact rows: id, name, style, type, OG, FG, ABV, IBU, colour.

Fetch one recipe in full, or just the sections you need.

Args: recipe_id: The recipe _id from list_recipes. sections: Optional subset of: fermentables, hops, yeast, miscs, mash, fermentation, water, measurements, notes. Omit for everything.

Returns: The recipe with grain bill percentages, hop schedule, mash and fermentation steps, and target figures, in both unit systems.

List inventory for one ingredient category.

Note: this returns only items you have added to your own inventory or set an amount on. It is not Brewfather's full ingredient database.

Args: category: One of fermentables, hops, miscs, yeasts. in_stock_only: Only items with a positive inventory amount. Default True.

Returns: Items with inventory amounts converted (fermentables in lb, hops and miscs in oz, yeast as pack counts), plus the relevant spec figures.

Compute brewhouse efficiency across recent batches.

For each batch: potential points from the grain bill, measured OG points, and the measured volume, combined as (og_points * volume_gal) / potential_points.

Per-fermentable potential comes from Brewfather's stored potential field when present (the figure the app itself calculates with), falling back to 46 * yield/100.

Args: limit: How many recent completed/archived batches to consider. Default 15. grain_only: Skip batches containing extract, sugar or other non-mashed fermentables, which inflate the figure. Default True. volume_basis: "fermenter" (default, matches Brewfather's own Brew House Efficiency — volume into the fermenter, so kettle losses count against you) or "post_boil" (kettle volume at flameout, which reads higher by exactly the transfer loss).

Returns: Per batch: name, brew date, target vs measured OG, target vs measured volume, computed efficiency, and Brewfather's stored figure with the delta between them. Then aggregates: mean, median, standard deviation, overall and split by batch size.

Line up 2-5 batches side by side on one dimension.

Rows are aligned by ingredient or step name, with an explicit null where a batch does not use that item — absence is usually the thing you are looking for when comparing versions of a recipe.

Args: batch_ids: Between 2 and 5 batch _id values. dimension: One of grain, hops, water, fermentation, measurements.

Returns: An aligned table: one row per ingredient or measurement, one column per batch, plus totals where a total is meaningful.

Verify credentials and report server configuration.

Makes one minimal API call. Never echoes credential values.

Returns: Connection status, the configured unit system and cache TTL, and cache hit statistics for this session.