Recipes

Query and manage your brewery's recipes via the Brewgenix REST API.

Get Recipe

Returns a single recipe by its ID, including style information.

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

Path Parameters

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

Authentication

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

Example Request

curl "https://brewgenix.app/api/v1/my-brewery/recipes/e5f6a7b8-..." \
  -H "Authorization: Bearer bgx_<your-key>"

Example Response

{
  "id": "e5f6a7b8-...",
  "name": "West Coast IPA",
  "description": "Clean, bitter, and aromatic.",
  "author": "Head Brewer",
  "batch_volume": 20,
  "boil_time_minutes": 60,
  "fermentables": [...],
  "hops": [...],
  "yeasts": [...],
  "miscellaneous": [],
  "styles": { "id": "...", "name": "American IPA" },
  "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`	Recipe not found.
`500`	Internal server error.

List Recipes

Returns a paginated list of recipes in your brewery account.

GET /api/v1/{account}/recipes

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 recipe name.

Authentication

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

Example Request

curl "https://brewgenix.app/api/v1/my-brewery/recipes?q=IPA" \
  -H "Authorization: Bearer bgx_<your-key>"

Example Response

{
  "data": [
    {
      "id": "e5f6a7b8-...",
      "name": "West Coast IPA",
      "batch_volume": 20,
      "boil_time_minutes": 60,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "count": 1,
  "page": 1,
  "pageSize": 20,
  "pageCount": 1
}

Error Responses

Status	Description
`401`	Missing or invalid API key.
`400`	Invalid query parameters.
`500`	Internal server error.

Create Recipe

Creates a new recipe in your brewery account.

POST /api/v1/{account}/recipes

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

Field	Type	Required	Description
`name`	string	Yes	Recipe name.
`batch_volume`	number	No	Target batch volume in litres. Defaults to `20`.
`boil_time_minutes`	integer	No	Boil duration in minutes. Defaults to `60`.
`description`	string	No	Recipe description or notes.
`author`	string	No	Recipe author.
`style_id`	string	No	UUID of the beer style to associate with this recipe.
`fermentables`	array	No	Array of fermentable usage objects. Defaults to `[]`.
`hops`	array	No	Array of hop usage objects. Defaults to `[]`.
`yeasts`	array	No	Array of yeast usage objects. Defaults to `[]`.
`miscellaneous`	array	No	Array of miscellaneous ingredient usage objects. Defaults to `[]`.

Example Request

curl -X POST "https://brewgenix.app/api/v1/my-brewery/recipes" \
  -H "Authorization: Bearer bgx_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast IPA",
    "batch_volume": 20,
    "boil_time_minutes": 60,
    "description": "Clean, bitter, and aromatic.",
    "author": "Head Brewer"
  }'

Example Response

{
  "id": "e5f6a7b8-...",
  "name": "West Coast IPA",
  "description": "Clean, bitter, and aromatic.",
  "author": "Head Brewer",
  "batch_volume": 20,
  "boil_time_minutes": 60,
  "fermentables": [],
  "hops": [],
  "yeasts": [],
  "miscellaneous": [],
  "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).
`500`	Internal server error.

Update Recipe

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

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

Path Parameters

Parameter	Type	Description
`account`	string	Your brewery account slug (visible in the app URL).
`id`	string	The recipe 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	Recipe name.
`batch_volume`	number	Target batch volume in litres.
`boil_time_minutes`	integer	Boil duration in minutes.
`description`	string	Recipe description or notes.
`author`	string	Recipe author.
`style_id`	string	UUID of the beer style to associate with this recipe.
`fermentables`	array	Replaces the entire fermentables array.
`hops`	array	Replaces the entire hops array.
`yeasts`	array	Replaces the entire yeasts array.
`miscellaneous`	array	Replaces the entire miscellaneous ingredients array.

Example Request

curl -X PATCH "https://brewgenix.app/api/v1/my-brewery/recipes/e5f6a7b8-..." \
  -H "Authorization: Bearer bgx_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast IPA v2",
    "boil_time_minutes": 90,
    "description": "Extended boil for more bitterness."
  }'

Example Response

{
  "id": "e5f6a7b8-...",
  "name": "West Coast IPA v2",
  "description": "Extended boil for more bitterness.",
  "author": "Head Brewer",
  "batch_volume": 20,
  "boil_time_minutes": 90,
  "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`	Recipe not found.
`422`	Validation failed (e.g. invalid field value).
`500`	Internal server error.

Delete Recipe

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

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

Path Parameters

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

Authentication

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

Example Request

curl -X DELETE "https://brewgenix.app/api/v1/my-brewery/recipes/e5f6a7b8-..." \
  -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`	Recipe not found.
`500`	Internal server error.

List Recipe Versions

Returns a paginated list of saved versions for a recipe, sorted newest first.

GET /api/v1/{account}/recipes/{id}/versions

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based).
`limit`	integer	`10`	Number of results per page. Maximum `100`.

Authentication

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

Example Request

curl "https://brewgenix.app/api/v1/my-brewery/recipes/e5f6a7b8-.../versions?page=1&limit=10" \
  -H "Authorization: Bearer bgx_<your-key>"

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "recipe_id": "e5f6a7b8-...",
      "version_number": 3,
      "description": "Competition entry - locked for reference",
      "is_locked": true,
      "name": "West Coast IPA",
      "batch_volume": 20,
      "boil_time_minutes": 60,
      "created_at": "2026-03-01T14:00:00Z"
    }
  ],
  "count": 3,
  "page": 1,
  "pageSize": 10,
  "pageCount": 1
}

Error Responses

Status	Description
`401`	Missing or invalid API key.
`422`	Invalid query parameters.
`500`	Internal server error.

Get Recipe Version

Returns a single version snapshot by its ID.

GET /api/v1/{account}/recipes/{id}/versions/{versionId}

Path Parameters

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

Authentication

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

Example Request

curl "https://brewgenix.app/api/v1/my-brewery/recipes/e5f6a7b8-.../versions/a1b2c3d4-..." \
  -H "Authorization: Bearer bgx_<your-key>"

Example Response

{
  "id": "a1b2c3d4-...",
  "recipe_id": "e5f6a7b8-...",
  "account_id": "...",
  "version_number": 3,
  "description": "Competition entry - locked for reference",
  "is_locked": true,
  "name": "West Coast IPA",
  "author": "Head Brewer",
  "batch_volume": 20,
  "boil_time_minutes": 60,
  "fermentables": [...],
  "hops": [...],
  "yeasts": [...],
  "miscellaneous": [],
  "mash_profile": null,
  "fermentation_profile": null,
  "water_profile": null,
  "created_at": "2026-03-01T14:00:00Z"
}

Error Responses

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

Create Recipe Version

Creates a new version snapshot of the current recipe state. The snapshot captures all recipe fields at the moment of the call. Use is_locked: true to make the version immutable (locked versions cannot be deleted).

POST /api/v1/{account}/recipes/{id}/versions

Path Parameters

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

Authentication

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

Request Body

Field	Type	Required	Description
`description`	string	No	A short label for this version (max 500 characters).
`is_locked`	boolean	No	If `true`, the version is locked and cannot be deleted. Defaults to `false`.

Example Request

curl -X POST "https://brewgenix.app/api/v1/my-brewery/recipes/e5f6a7b8-.../versions" \
  -H "Authorization: Bearer bgx_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Competition entry v3",
    "is_locked": true
  }'

Example Response

{
  "id": "a1b2c3d4-...",
  "recipe_id": "e5f6a7b8-...",
  "version_number": 4,
  "description": "Competition entry v3",
  "is_locked": true,
  "name": "West Coast IPA",
  "batch_volume": 20,
  "boil_time_minutes": 60,
  "created_at": "2026-03-01T15:00:00Z"
}

Error Responses

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

Delete Recipe Version

Deletes a non-locked recipe version. Locked versions cannot be deleted and will return 409 Conflict.

DELETE /api/v1/{account}/recipes/{id}/versions/{versionId}

Path Parameters

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

Authentication

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

Example Request

curl -X DELETE "https://brewgenix.app/api/v1/my-brewery/recipes/e5f6a7b8-.../versions/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`	Version not found.
`409`	Version is locked and cannot be deleted.
`500`	Internal server error.