Hops

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

Get Hop

Returns a single hop by its ID.

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

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).
`id`	string	The hop 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/hops/a1b2c3d4-e5f6-..." \
  -H "Authorization: Bearer bgx_<your-key>"

Example Response

{
  "id": "a1b2c3d4-...",
  "name": "Citra",
  "origin": "US",
  "purpose": "aroma",
  "form": "pellet",
  "alpha_acids_min_in_pct": 11.0,
  "alpha_acids_max_in_pct": 13.0,
  "substitutes": [],
  "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`	Hop not found.
`500`	Internal server error.

List Hops

Returns a paginated list of hops in your brewery account.

GET /api/v1/{account}/hops

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 hops by name.

Authentication

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

Example Request

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

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Citra",
      "origin": "US",
      "purpose": "Aroma",
      "form": "Pellet",
      "alpha_acids_min_in_pct": 11.0,
      "alpha_acids_max_in_pct": 13.0,
      "beta_acids_min_in_pct": 3.5,
      "beta_acids_max_in_pct": 4.5,
      "notes": "High in myrcene...",
      "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 hop objects.
`count`	integer	Total number of hops matching the query.
`page`	integer	Current page number.
`pageSize`	integer	Number of results returned on this page.
`pageCount`	integer	Total number of pages.

Hop Object

Field	Type	Description
`id`	string	Unique identifier (UUID).
`name`	string	Hop variety name.
`origin`	string	Country of origin.
`purpose`	string	Primary use: `Bittering`, `Aroma`, or `Dual`.
`form`	string	Physical form: `Pellet`, `Leaf`, or `Extract`.
`alpha_acids_min_in_pct`	number	Minimum alpha acid percentage.
`alpha_acids_max_in_pct`	number	Maximum alpha acid percentage.
`beta_acids_min_in_pct`	number	Minimum beta acid percentage.
`beta_acids_max_in_pct`	number	Maximum beta acid percentage.
`notes`	string	Additional notes or flavour descriptors.
`created_at`	string	ISO 8601 timestamp when the hop 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 Hop

Creates a new hop variety in your brewery account.

POST /api/v1/{account}/hops

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	Hop variety name.
`purpose`	string	Yes	Primary use: `aroma`, `bittering`, or `both`.
`form`	string	Yes	Physical form: `pellet`, `whole`, `cryo`, or `co2 extract`.
`origin`	string	No	Country of origin.
`description`	string	No	Description or flavour notes.
`alpha_acids_min_in_pct`	number	No	Minimum alpha acid percentage (0–100).
`alpha_acids_max_in_pct`	number	No	Maximum alpha acid percentage (0–100). Must be ≥ min.
`beta_acids_min_in_pct`	number	No	Minimum beta acid percentage (0–100).
`beta_acids_max_in_pct`	number	No	Maximum beta acid percentage (0–100). Must be ≥ min.
`cohumulone_min_in_pct`	number	No	Minimum cohumulone percentage (0–100).
`cohumulone_max_in_pct`	number	No	Maximum cohumulone percentage (0–100). Must be ≥ min.
`myrcene_min_in_pct`	number	No	Minimum myrcene percentage (0–100).
`myrcene_max_in_pct`	number	No	Maximum myrcene percentage (0–100). Must be ≥ min.
`aroma_citrus`	number	No	Citrus aroma intensity (0–5).
`aroma_stone_fruit`	number	No	Stone fruit aroma intensity (0–5).
`aroma_berry`	number	No	Berry aroma intensity (0–5).
`aroma_floral`	number	No	Floral aroma intensity (0–5).
`aroma_grassy`	number	No	Grassy aroma intensity (0–5).
`aroma_herbal`	number	No	Herbal aroma intensity (0–5).
`aroma_spice`	number	No	Spice aroma intensity (0–5).
`aroma_resin_pine`	number	No	Resin/pine aroma intensity (0–5).

Example Request

curl -X POST "https://app.brewgenix.com/api/v1/my-brewery/hops" \
  -H "Authorization: Bearer bgx_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Galaxy",
    "origin": "AU",
    "purpose": "aroma",
    "form": "pellet",
    "alpha_acids_min_in_pct": 11.0,
    "alpha_acids_max_in_pct": 16.0,
    "aroma_citrus": 4,
    "aroma_stone_fruit": 3
  }'

Example Response

{
  "id": "c3d4e5f6-...",
  "name": "Galaxy",
  "origin": "AU",
  "purpose": "aroma",
  "form": "pellet",
  "alpha_acids_min_in_pct": 11.0,
  "alpha_acids_max_in_pct": 16.0,
  "aroma_citrus": 4,
  "aroma_stone_fruit": 3,
  "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, min > max for a range field).
`500`	Internal server error.

Update Hop

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

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

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).
`id`	string	The hop 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	Hop variety name.
`purpose`	string	Primary use: `aroma`, `bittering`, or `both`.
`form`	string	Physical form: `pellet`, `whole`, `cryo`, or `co2 extract`.
`origin`	string	Country of origin.
`description`	string	Description or flavour notes.
`alpha_acids_min_in_pct`	number	Minimum alpha acid percentage (0–100).
`alpha_acids_max_in_pct`	number	Maximum alpha acid percentage (0–100). Must be ≥ min.
`beta_acids_min_in_pct`	number	Minimum beta acid percentage (0–100).
`beta_acids_max_in_pct`	number	Maximum beta acid percentage (0–100). Must be ≥ min.
`aroma_citrus`	number	Citrus aroma intensity (0–5).
`aroma_stone_fruit`	number	Stone fruit aroma intensity (0–5).
`aroma_berry`	number	Berry aroma intensity (0–5).
`aroma_floral`	number	Floral aroma intensity (0–5).
`aroma_grassy`	number	Grassy aroma intensity (0–5).
`aroma_herbal`	number	Herbal aroma intensity (0–5).
`aroma_spice`	number	Spice aroma intensity (0–5).
`aroma_resin_pine`	number	Resin/pine aroma intensity (0–5).

Example Request

curl -X PATCH "https://app.brewgenix.com/api/v1/my-brewery/hops/a1b2c3d4-..." \
  -H "Authorization: Bearer bgx_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "alpha_acids_min_in_pct": 12.0,
    "alpha_acids_max_in_pct": 14.0,
    "description": "Updated flavour notes"
  }'

Example Response

{
  "id": "a1b2c3d4-...",
  "name": "Citra",
  "origin": "US",
  "purpose": "aroma",
  "form": "pellet",
  "alpha_acids_min_in_pct": 12.0,
  "alpha_acids_max_in_pct": 14.0,
  "description": "Updated flavour 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`	Hop not found.
`422`	Validation failed (e.g. min > max for a range field).
`500`	Internal server error.

Delete Hop

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

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

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).
`id`	string	The hop 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/hops/a1b2c3d4-..." \
  -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`	Hop not found.
`500`	Internal server error.