BrewForge Docs

Add ingredient stock

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

POST
/api/v1/actions/add_stock

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.

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

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

Ingredient type: "fermentable" (malts, sugars, extracts), "hop", "yeast" or "misc" (water agents, finings, spices, ...).

Value in"fermentable" | "hop" | "yeast" | "misc"
amount*number

How much was bought, in unit (e.g. 5 with unit "kg", 100 for 100 g, 2 packs of yeast).

Range0 < value
unit?string

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).

Value in"g" | "kg" | "oz" | "lb" | "mg" | "pkg" | "ml" | "cells" | "each"
lot?string

Lot or batch number on the bag (e.g. "L2025-118").

Lengthlength <= 100
expiry_date?string

Best before / expiry date, YYYY-MM-DD (e.g. "2027-03-31"); YYYY-MM means the last day of that month.

Match^\d{4}-\d{2}(-\d{2})?$
purchase_date?string

When it was bought, YYYY-MM-DD (e.g. "2026-11-11"); YYYY-MM means the last day of that month.

Match^\d{4}-\d{2}(-\d{2})?$
supplier?string

Where it was bought (e.g. "Hopfen der Welt").

Lengthlength <= 200
cost_per_kg?number

Price per kg, for fermentables and hops, in the user's currency (e.g. 2.4).

Range0 <= value
cost_per_unit?number

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).

Range0 <= value
total_cost?number

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.

Range0 <= value
notes?string

Free text.

Lengthlength <= 500
alpha_acid_pct?number

Hops only: alpha acid % of this lot (e.g. 13.2); default is the catalog value.

Range0 <= value <= 30
form?string

Hops only: "pellet" (default), "whole", "cryo" or "extract".

Value in"pellet" | "whole" | "cryo" | "extract"
harvest_year?integer

Hops only: crop year (e.g. 2025).

Range1900 <= value <= 2100
manufacturing_date?string

Yeast only: production date, YYYY-MM-DD (e.g. "2027-03-31"); YYYY-MM means the last day of that month.

Match^\d{4}-\d{2}(-\d{2})?$
[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/add_stock" \  -H "Content-Type: application/json" \  -d '{    "ingredient": "string",    "amount": 0  }'
{
  "stock": {
    "id": "string",
    "type": "fermentable",
    "name": "string",
    "ingredient_id": "string",
    "amount": 0,
    "unit": "string",
    "status": "in_stock",
    "lot": "string",
    "expiry_date": "string",
    "purchase_date": "string",
    "supplier": "string",
    "cost_per_kg": 0,
    "cost_per_unit": 0,
    "alpha_acid_pct": 0,
    "form": "string",
    "harvest_year": 0,
    "lab": "string",
    "notes": "string"
  },
  "merged_into_existing": true,
  "added": {
    "amount": 0,
    "unit": "string"
  },
  "price": {
    "cost_per_kg": 0,
    "cost_per_unit": 0,
    "per": "string",
    "currency": "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": {}
  }
}