BrewForge Docs

Find ingredients

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

POST
/api/v1/actions/find_ingredients

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.

Scope: inventory:read (or read).

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:read

Request Body

application/json

query?string

Text the name contains, e.g. "citra", "pilsner", "us-05". Required for scope "catalog" (at least 2 characters).

type?string

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

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

"picker" (default): ingredients the user can use. "catalog": search all packages, including ones not in the picker.

Value in"picker" | "catalog"
own_only?boolean

Only the user's own ingredients (My Ingredients and imported ones).

limit?integer

How many rows to return, 1-100 (default 25).

Range1 <= value <= 100
cursor?string

next_cursor from the previous page, to get the next page. Omit for the first page.

[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/find_ingredients" \  -H "Content-Type: application/json" \  -d '{}'
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "type": "fermentable",
      "package": "string",
      "package_id": "string",
      "own": true,
      "in_picker": true,
      "property1": null,
      "property2": null
    }
  ],
  "next_cursor": "string",
  "hint": "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": {}
  }
}