Fermentables

Query your brewery's fermentable inventory via the Brewgenix REST API.

Get Fermentable

Returns a single fermentable by its ID.

GET /api/v1/{account}/fermentables/{id}

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).
`id`	string	The fermentable UUID.

Authentication

Requires a valid API key passed as a Bearer token. See Authentication.

Example Request

curl "https://app.brewgenix.com/api/v1/my-brewery/fermentables/b2c3d4e5-f6a7-..." \
  -H "Authorization: Bearer bgx_<your-key>"

Example Response

{
  "id": "b2c3d4e5-...",
  "name": "Pale Malt (2 Row)",
  "type": "grain",
  "origin": "US",
  "supplier": "Briess",
  "color_lovibond": 1.8,
  "potential_ppg": 37.0,
  "yield_pct": 79.0,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

Error Responses

Status	Description
`401`	Missing or invalid API key.
`404`	Fermentable not found.
`500`	Internal server error.

List Fermentables

Returns a paginated list of fermentables in your brewery account.

GET /api/v1/{account}/fermentables

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based).
`limit`	integer	`20`	Number of results per page. Maximum `100`.
`q`	string	-	Search query. Filters by name, origin, or supplier.
`type`	string	-	Filter by fermentable type (e.g. `grain`, `adjunct`, `extract`).

Authentication

Requires a valid API key passed as a Bearer token. See Authentication.

Example Request

curl "https://app.brewgenix.com/api/v1/my-brewery/fermentables?page=1&limit=20&type=grain" \
  -H "Authorization: Bearer bgx_<your-key>"

Example Response

{
  "data": [
    {
      "id": "b2c3d4e5-...",
      "name": "Pale Malt (2 Row)",
      "type": "grain",
      "origin": "US",
      "supplier": "Briess",
      "color_lovibond": 1.8,
      "potential_sg": 1.037,
      "max_in_batch_pct": 100.0,
      "moisture_pct": 4.0,
      "protein_pct": 11.7,
      "notes": "Base malt for most American ale styles.",
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    }
  ],
  "count": 1,
  "page": 1,
  "pageSize": 20,
  "pageCount": 1
}

Response Fields

Top-level

Field	Type	Description
`data`	array	Array of fermentable objects.
`count`	integer	Total number of fermentables matching the query.
`page`	integer	Current page number.
`pageSize`	integer	Number of results returned on this page.
`pageCount`	integer	Total number of pages.

Fermentable Object

Field	Type	Description
`id`	string	Unique identifier (UUID).
`name`	string	Fermentable name.
`type`	string	Type: `grain`, `adjunct`, `extract`, `sugar`, or `fruit`.
`origin`	string	Country of origin.
`supplier`	string	Maltster or supplier name.
`color_lovibond`	number	Colour in degrees Lovibond (°L).
`potential_sg`	number	Maximum potential specific gravity contribution.
`max_in_batch_pct`	number	Maximum recommended percentage in a batch.
`moisture_pct`	number	Moisture content percentage.
`protein_pct`	number	Protein content percentage.
`notes`	string	Additional notes or usage guidance.
`created_at`	string	ISO 8601 timestamp when the fermentable was created.
`updated_at`	string	ISO 8601 timestamp of the last update.

Error Responses

Status	Description
`401`	Missing or invalid API key.
`400`	Invalid query parameters (e.g. `limit` exceeds 100).
`500`	Internal server error.

Create Fermentable

Creates a new fermentable in your brewery account.

POST /api/v1/{account}/fermentables

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).

Authentication

Requires a valid API key passed as a Bearer token. See Authentication.

Request Body

Send a JSON object with the following fields:

Field	Type	Required	Description
`name`	string	Yes	Fermentable name.
`type`	string	Yes	Type: `grain`, `sugar`, `liquid_extract`, `dry_extract`, `adjunct`, or `other`.
`origin`	string	No	Country of origin.
`supplier`	string	No	Maltster or supplier name.
`description`	string	No	Description or usage notes.
`color_lovibond`	number	No	Colour in degrees Lovibond (°L). Must be ≥ 0.
`potential_ppg`	number	No	Potential points per pound per gallon. Must be ≥ 0.
`yield_pct`	number	No	Yield percentage (0–100).
`exclude_from_total`	boolean	No	Whether to exclude from total grain bill. Defaults to `false`.
`not_fermentable`	boolean	No	Whether the fermentable is non-fermentable. Defaults to `false`.
`category`	string	No	Grain category: `base_6row`, `base_maris_otter`, `base_munich`, `base_pilsner`, `base_wheat`, `base_vienna`, `crystal_caramel`, `roasted`, or `acidulated`.
`max_in_batch_pct`	number	No	Maximum recommended percentage in a batch (0–100).
`moisture_pct`	number	No	Moisture content percentage (0–100).
`protein_pct`	number	No	Protein content percentage (0–100).
`diastatic_power`	number	No	Diastatic power in Lintner. Must be ≥ 0.
`notes`	string	No	Additional notes.

Example Request

curl -X POST "https://app.brewgenix.com/api/v1/my-brewery/fermentables" \
  -H "Authorization: Bearer bgx_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pale Malt (2 Row)",
    "type": "grain",
    "origin": "US",
    "supplier": "Briess",
    "color_lovibond": 1.8,
    "potential_ppg": 37.0,
    "yield_pct": 79.0
  }'

Example Response

{
  "id": "b2c3d4e5-...",
  "name": "Pale Malt (2 Row)",
  "type": "grain",
  "origin": "US",
  "supplier": "Briess",
  "color_lovibond": 1.8,
  "potential_ppg": 37.0,
  "yield_pct": 79.0,
  "exclude_from_total": false,
  "not_fermentable": false,
  "created_at": "2026-02-24T10:00:00Z",
  "updated_at": "2026-02-24T10:00:00Z"
}

Error Responses

Status	Description
`401`	Missing or invalid API key.
`400`	Request body is not valid JSON.
`422`	Validation failed (e.g. missing required field, invalid type value).
`500`	Internal server error.

Update Fermentable

Updates an existing fermentable. Only the fields provided in the request body are updated (PATCH semantics).

PATCH /api/v1/{account}/fermentables/{id}

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).
`id`	string	The fermentable UUID.

Authentication

Requires a valid API key passed as a Bearer token. See Authentication.

Request Body

All fields are optional. Provide only the fields you want to update.

Field	Type	Description
`name`	string	Fermentable name.
`type`	string	Type: `grain`, `sugar`, `liquid_extract`, `dry_extract`, `adjunct`, or `other`.
`origin`	string	Country of origin.
`supplier`	string	Maltster or supplier name.
`description`	string	Description or usage notes.
`color_lovibond`	number	Colour in degrees Lovibond (°L). Must be ≥ 0.
`potential_ppg`	number	Potential points per pound per gallon. Must be ≥ 0.
`yield_pct`	number	Yield percentage (0–100).
`exclude_from_total`	boolean	Whether to exclude from total grain bill.
`not_fermentable`	boolean	Whether the fermentable is non-fermentable.
`category`	string	Grain category (e.g. `base_pilsner`, `crystal_caramel`, `roasted`).
`max_in_batch_pct`	number	Maximum recommended percentage in a batch (0–100).
`moisture_pct`	number	Moisture content percentage (0–100).
`protein_pct`	number	Protein content percentage (0–100).
`diastatic_power`	number	Diastatic power in Lintner. Must be ≥ 0.
`notes`	string	Additional notes.

Example Request

curl -X PATCH "https://app.brewgenix.com/api/v1/my-brewery/fermentables/b2c3d4e5-..." \
  -H "Authorization: Bearer bgx_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "color_lovibond": 2.0,
    "notes": "Updated usage notes"
  }'

Example Response

{
  "id": "b2c3d4e5-...",
  "name": "Pale Malt (2 Row)",
  "type": "grain",
  "color_lovibond": 2.0,
  "notes": "Updated usage notes",
  "updated_at": "2026-02-24T11:00:00Z"
}

Error Responses

Status	Description
`401`	Missing or invalid API key.
`400`	Request body is not valid JSON.
`404`	Fermentable not found.
`422`	Validation failed (e.g. invalid type value).
`500`	Internal server error.

Delete Fermentable

Soft-deletes a fermentable. The record is marked as deleted and will no longer appear in list or get requests.

DELETE /api/v1/{account}/fermentables/{id}

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).
`id`	string	The fermentable UUID.

Authentication

Requires a valid API key passed as a Bearer token. See Authentication.

Example Request

curl -X DELETE "https://app.brewgenix.com/api/v1/my-brewery/fermentables/b2c3d4e5-..." \
  -H "Authorization: Bearer bgx_<your-key>"

Response

Returns 204 No Content on success with an empty body.

Error Responses

Status	Description
`401`	Missing or invalid API key.
`404`	Fermentable not found.
`500`	Internal server error.