BrewForge Docs

Create a recipe / brew

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. Scope: `brews:write` (or `write`).

POST
/api/v1/actions/create_brew

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.

Scope: brews:write (or write).

AuthorizationBearer <token>

API token in format: bfk_. Each operation lists the token scope it requires (the scopes are listed below).

  • read: Read everything (all areas)
  • write: Create, change and delete everything (all areas)
  • brews:read: List and view brews
  • brews:write: Create, update, delete brews and notes
  • inventory:read: List inventory items
  • inventory:write: Create, update, delete inventory items
  • equipment:read: List equipment profiles
  • equipment:write: Create, update, delete equipment profiles
  • styles:read: List style profiles
  • styles:write: Create, update, delete style profiles
  • profiles:read: List mash, fermentation, and water profiles
  • custom-fields:read: List custom field definitions
  • custom-fields:write: Create, update, delete custom field definitions
  • profiles:write: Create, update, delete mash, fermentation, and water profiles
  • cellar:read: View cellar, packaged stock, tap lists, and labels
  • cellar:write: Manage cellar, packaging, stock, tap lists, and labels
  • settings:read: View preferences, imports, calculators, and your data export
  • settings:write: Change preferences and undo imports
  • community:read: View community, feedback, tickets, inbox, and account overview
  • community:write: Post, vote, and reply in community, feedback, and tickets

In: header

Scope: brews:write

Request Body

application/json

name*string

Name of the beer, e.g. "West Coast IPA".

Length1 <= length <= 200
planned_date?string

Planned brew day; makes the brew "planned" and gives it a batch number (YYYY-MM-DD, e.g. "2026-11-21").

Match^\d{4}-\d{2}-\d{2}$
ready_by_date?string

Date the beer must be ready (drinkable) by (YYYY-MM-DD, e.g. "2026-12-24").

Match^\d{4}-\d{2}-\d{2}$
ready_by_note?string

What it is ready for, e.g. "Christmas party".

Lengthlength <= 200
description?string

Free-text description or notes.

Lengthlength <= 5000
tags?array<>

Tags, e.g. ["hoppy", "competition"].

brew_type?string

"all_grain" (default), "partial_mash" or "extract".

Value in"all_grain" | "partial_mash" | "extract"
style?string

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?string

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?string

Name or id of one of the brewer's mash profiles (e.g. "Single infusion 67°C"). Replaces the mash steps.

fermentation_profile?string

Name or id of one of the brewer's fermentation profiles (e.g. "Ale 19°C"). Replaces the fermentation stages.

water_source_profile?string

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?string

Name or id of one of the brewer's water profiles (e.g. "Balanced"). Used as the recipe's target water.

batch_volume_l?number

Batch volume in liters (into the fermenter), e.g. 20.

Range0 < value <= 10000
boil_time_min?number

Boil time in minutes, e.g. 60.

Range0 <= value <= 600
efficiency_pct?number

Brewhouse efficiency in %, e.g. 72.

Range1 <= value <= 100
mash_steps?array<>

The full list of mash rests in order; replaces the current steps.

fermentation_stages?array<>

The full list of fermentation stages in order; replaces the current stages.

temp_unit?string

Unit of the temperatures you send: "c" (°C, default) or "f" (°F).

Value in"c" | "f"
fg_override_sg?|

Planned FG to use instead of the one calculated from yeast attenuation, as SG (e.g. 1.012). null removes the override.

target_og?number

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?number

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.

Range0 <= value <= 200
gravity_unit?string

Unit of the gravity values you send: "sg" (specific gravity, e.g. 1.012; default) or "plato" (°P, e.g. 3.1).

Value in"sg" | "plato"
fermentables?array<>

Fermentables, e.g. [{"name": "Pale Ale Malt", "amount_g": 5000}].

hops?array<>

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?array<>

Yeasts, e.g. [{"name": "SafAle US-05"}] (1 pack by default).

miscs?array<>

Other additions (salts, finings, spices), e.g. [{"name": "Gypsum", "amount": 5, "use": "mash"}].

[key: string]?never

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://brewforge.sh/api/v1/actions/create_brew" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{
  "brew": {
    "id": "string",
    "name": "string",
    "batch_number": 0,
    "status": "idea",
    "recipe_id": "string",
    "version": "string",
    "planned_date": "string",
    "brew_date": "string",
    "ready_by_date": "string"
  },
  "planned": {
    "og_sg": 0,
    "og_plato": 0,
    "fg_sg": 0,
    "fg_plato": 0,
    "abv_pct": 0,
    "ibu": 0,
    "color_ebc": 0
  },
  "batch_volume_l": 0,
  "equipment": {
    "profile": "string",
    "brewhouse_efficiency_pct": 0,
    "mash_efficiency_pct": 0
  },
  "style_fit": [
    "string"
  ],
  "recipe": {
    "property1": null,
    "property2": null
  },
  "notes": [
    "string"
  ]
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}