BrewForge Docs

Create or edit an own ingredient

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

POST
/api/v1/actions/save_custom_ingredient

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.

Scope: inventory: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: inventory:write

Request Body

application/json

ingredient?string

Edit this own ingredient (id or exact name, e.g. "Homegrown Cascade"). Leave out to create a new one.

type?string

Required to create: fermentable, hop, yeast or misc.

Value in"fermentable" | "hop" | "yeast" | "misc"
name?string

Name (required to create), e.g. "Homegrown Cascade".

Lengthlength <= 200
kind?string

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

Fermentable color in EBC (e.g. 3.5 for Pilsner malt).

Range0 <= value <= 4000
potential_ppg?number

Fermentable extract potential in PPG (e.g. 37).

Range0 <= value <= 50
origin?string

Country of origin (e.g. "Germany").

Lengthlength <= 100
maltster?string

Fermentable maltster/brand.

Lengthlength <= 200
non_fermentable?boolean

Fermentable that yeast cannot ferment (lactose, maltodextrin).

max_usage_pct?number

Fermentable: max share in the grist, %.

Range0 <= value <= 100
alpha_acid_pct?number

Hop alpha acid % (e.g. 7.5).

Range0 <= value <= 30
beta_acid_pct?number

Hop beta acid %.

Range0 <= value <= 30
purpose?string

Hop purpose: bittering, aroma or dual.

Value in"bittering" | "aroma" | "dual"
harvest_year?integer

Hop harvest (crop) year, e.g. 2025.

Range1900 <= value <= 2100
aroma?string

Hop aroma profile.

Lengthlength <= 1000
lab?string

Yeast lab (e.g. "Fermentis").

Lengthlength <= 100
product_id?string

Yeast product code (e.g. "US-05").

Lengthlength <= 50
form?string

Yeast form: dry or liquid.

Value in"dry" | "liquid"
attenuation_min_pct?number

Yeast attenuation, low end %.

Range0 <= value <= 100
attenuation_max_pct?number

Yeast attenuation, high end %.

Range0 <= value <= 100
temp_min_c?number

Yeast lowest fermentation temperature, °C.

Range-5 <= value <= 50
temp_max_c?number

Yeast highest fermentation temperature, °C.

Range-5 <= value <= 50
flocculation?string

Yeast flocculation.

Value in"low" | "medium" | "high" | "very_high"
alcohol_tolerance_pct?number

Yeast alcohol tolerance, % ABV.

Range0 <= value <= 25
default_unit?string

Misc: unit it is usually dosed and stocked in.

Value in"g" | "mg" | "ml" | "tsp" | "tbsp" | "each"
description?string

Free text.

Lengthlength <= 2000
move_to_my_ingredients?boolean

Edit only: move an imported ingredient (from an import package) into My Ingredients. Stock, recipes and orders stay linked.

[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/save_custom_ingredient" \  -H "Content-Type: application/json" \  -d '{}'
{
  "ingredient": {
    "id": "string",
    "name": "string",
    "type": "fermentable",
    "package": "string",
    "property1": null,
    "property2": null
  },
  "created": true,
  "moved": "moved"
}
{
  "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": {}
  }
}