API

REST API version 2

API version 1 is deprecated and will be discontinued, please convert to version 2 (this version).

Changes in version 2 of the API include:

• A new method of paging the GET requests that lists multiple elements. The parameter "offset" is replaced with "start_after". Use the "_id" in the last element of the previous request to get to the next set of elements.

• The default ordering of elements has changed to use the "_id" field instead of the "name" field.

• Added new query parameters order_by and order_by_direction to enable customizing ordering of the result

• GET batches no longer have a default value for the "status" parameter

• Version 2 has an increased rate limit

• Measured values can now be updated for a batch PATCH

Disclaimer

Please keep yourself updated on the API documentation as important messages and changes will be listed above this disclaimer.

Data returned from the API will be in metric units. Requests are ordered by the "_id" field.

Authentication

The authorization header must consist of your userid:apikey (base64 encoded).

Example:

UserId: xyz123 API-key: 1234567890123456789012345678901234567890abcd Base 64 encode: "xyz123:1234567890123456789012345678901234567890abcd"

curl -H "authorization: Basic eHl6MTIzOjEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTBhYmNk" \
https://api.brewfather.app/v2/batches

In Postman, you can configure Basic Authorization by clicking the Authorization tab, selecting Basic Auth from the drop-down selector, and then typing the username (userid from above) and password (api-key from above) on the right of the colon on each row.

The API supports HTTPS traffic only (for security reasons).

Generate API-Key

In the Settings page, you can click GENERATE in the API-section to create your API-key. You can currently only have one API-key per account.

Scopes

Scopes control what the API-key can access. Currently, you can choose:

• Read Recipes

• Read Batches

• Edit Batches

• Read Inventory

• Edit Inventory

When you generate your API-key you can select different scopes that the API-key can access, when new scopes are added you might need to generate a new key with the new scopes to allow access to the new scopes.

Rate Limit

Currently, you can do a maximum of 500 calls per hour per API-key.

Rate limits can be changed at any time, build your integration to handle HTTP code 429 Too Many Requests, the response will include a Retry-After header.

Batches

Get Batches

GET https://api.brewfather.app/v2/batches

This endpoint allows you to list your batches. By default it returns batches with all statuses. Use the query parameter "status" to query for a given status.

Query Parameters

Name	Type	Description
include	array	Array of additional fields to include when complete is false. Example "recipe.fermentation,recipe.mash" to include the fermentation and mash profile.
complete	boolean	Valid values "True" or "False". Includes all the data in the result if True. Defaults to "False". If False only Name, Batch Number, Status, Brewer, Brew Date, Recipe Name is returned.
status	string	Valid values "Planning", "Brewing", "Fermenting", "Conditioning", "Completed", "Archived".
limit	number	Amount of documents to fetch. Defaults to 10. Max 50.
start_after	string	"_id" of the last item in the previous request
order_by	string	The field to order by, defaults to "_id"
order_by_direction	string	Direction to order result, valid values "asc" for ascending and "desc" for descending. Defaults to "asc"

Headers

Name	Type	Description
Authorization	string	See authentication.

200

[ array of Brewfather BATCH JSON ]

Get Batch

GET https://api.brewfather.app/v2/batches/:id

This endpoint allows you to fetch a specific batch. :id is the _id property from the batch JSON.

Query Parameters

Name	Type	Description
include	string	Array of fields to include. Example "recipe.fermentation,recipe.mash" to include the fermentation and mash profile. When omitted all fields are included. Default fields are included in addition to the requested fields.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

{ Brewfather BATCH JSON }

Update Batch

PATCH https://api.brewfather.app/v2/batches/:id

This endpoint allows you to update specific fields of a specific batch. Currently support setting the status and measured values, please let us know what fields you would like to be able to update via the API.

Requires API scope: batches.write

Request Body

All fields are optional. Send only the fields you want to update. To clear a measured value, send null.

Name	Type	Description
status	string	Valid values "Planning", "Brewing", "Fermenting", "Conditioning", "Completed", "Archived".
measuredMashPh	number	Mash pH. Value between 0 and 14. Set to null to clear.
measuredBoilSize	number	Pre-Boil Volume in Liters. Minimum value 0. Set to null to clear.
measuredFirstWortGravity	number	Pre-Sparge Gravity in SG. Value between 0.1 and 1.9 (e.g., 1.055). Set to null to clear.
measuredPreBoilGravity	number	Pre-Boil Gravity in SG. Value between 0.1 and 1.9 (e.g., 1.055). Set to null to clear.
measuredPostBoilGravity	number	Post-Boil Gravity in SG. Value between 0.1 and 1.9 (e.g., 1.055). Set to null to clear.
measuredKettleSize	number	Post-Boil Volume in Liters. Minimum value 0. Set to null to clear.
measuredOg	number	Original Gravity in SG. Value between 0.1 and 1.9 (e.g., 1.055). Set to null to clear.
measuredFermenterTopUp	number	Fermenter Top-Up Volume in Liters. Minimum value 0. Set to null to clear.
measuredBatchSize	number	Fermenter Volume in Liters. Minimum value 0. Set to null to clear.
measuredFg	number	Final Gravity in SG. Value between 0.1 and 1.9 (e.g., 1.011). Set to null to clear.
measuredBottlingSize	number	Final Bottling/Kegging Volume in Liters. Minimum value 0. Set to null to clear.
carbonationTemp	number	Carbonation Temperature in Celsius (°C). Value between -50 and 100. Set to null to clear.

Headers

Name	Type	Description
Authorization	string	See authentication.
Content-Type	string	application/json

200 Success

Updated

Note: If no valid fields are provided, returns "Nothing to update".

400 Bad Request

403 Forbidden

Example

Get Batch Last Reading

GET https://api.brewfather.app/v2/batches/:batch_id/readings/last

This endpoint allows you to fetch the latest reading received :batch_id is the _id property from the batch JSON.

Headers

Name	Type	Description
Authorization	string	See authentication.

200 Example (Time in milliseconds):

{
    "battery": 4.082377,
    "id": "GREEN",
    "rssi": -75,
    "temp": 5.1,
    "type": "iSpindel",
    "sg": 1.039,
    "time": 1572383500131,
    "angle": 32.8009
}

Get Batch All Readings

GET https://api.brewfather.app/v2/batches/:batch_id/readings

This endpoint allows you to fetch all readings stored in a batch. If you only need the latest reading use the call above. :batch_id is the _id property from the batch JSON.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

[ array of readings ]

Get Batch Brew Tracker

GET https://api.brewfather.app/v2/batches/:batch_id/brewtracker

This endpoint allows you to fetch the latest stored status of the brewtracker. Brew tracker does not get updated every second, position is calculated from start time of the stage. Brewfather triggers an update/save at certain events. :batch_id is the _id property from the batch JSON.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

{ brew tracker object }

Recipes

Get Recipes

GET https://api.brewfather.app/v2/recipes

This endpoint allows you to list your recipes.

Query Parameters

Name	Type	Description
include	string	Array of additional fields to include when complete is false. Example "fermentation,mash" to include the fermentation and mash profile.
complete	boolean	Valid values "True" or "False". Includes all the data in the result if True. Defaults to "False". If False only Name, Author, Style Name, Type is returned.
limit	number	Amount of documents to fetch. Defaults to 10. Max 50.
start_after	string	"_id" of the last item in the previous request
order_by	string	The field to order by, defaults to "_id"
order_by_direction	string	Direction to order result, valid values "asc" for ascending and "desc" for descending. Defaults to "asc"

Headers

Name	Type	Description
Authorization	string	See authentication.

200

[ array of Brewfather RECIPE JSON ]

Get Recipe

GET https://api.brewfather.app/v2/recipes/:id

This endpoint allows you to fetch a specific recipe. :id is the _id property from the recipe JSON.

Query Parameters

Name	Type	Description
include	string	Array of additional fields to include. Example "fermentation,mash" to include the fermentation and mash profile. When omitted all fields are included. Default fields are included in addition to the requested fields.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

{ Brewfather RECIPE JSON }

Inventory

Get Fermentables

GET https://api.brewfather.app/v2/inventory/fermentables

This endpoint allows you to list your inventory items. It will only list items you have added manually or edited the default values for, or added an inventory amount on.

Query Parameters

Name	Type	Description
inventory_negative	boolean	If true, only include items with inventory < 0
include	array	Array of additional fields to include when complete is false.
complete	boolean	Valid values "True" or "False". Includes all the data in the result if True. Defaults to "False".
inventory_exists	boolean	Valid values "True" or "False". If true, only include items with inventory > 0. Results will be ordered by inventory amount instead of _id.
limit	number	Amount of documents to fetch. Defaults to 10. Max 50.
start_after	string	"_id" of the last item in the previous request
order_by	string	The field to order by, defaults to "_id"
order_by_direction	string	Direction to order result, valid values "asc" for ascending and "desc" for descending. Defaults to "asc"

Headers

Name	Type	Description
Authorization	string	See authentication.

200

[ array of Brewfather JSON ]

Get Fermentable

GET https://api.brewfather.app/v2/inventory/fermentables/:id

This endpoint allows you to fetch a specific item.

Query Parameters

Name	Type	Description
include	string	Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

{ Brewfather JSON }

Update Fermentable

PATCH https://api.brewfather.app/v2/inventory/fermentables/:id

This endpoint allows you to update the inventory amount of a specific fermentable.

Requires API scope: inventory.write

Request Body

Name	Type	Description
inventory	number	Set the inventory amount to the given value. Takes precedence over inventory_adjust.
inventory_adjust	number	Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount.

Note: If both inventory and inventory_adjust are provided, inventory takes precedence and inventory_adjust is ignored.

Headers

Name	Type	Description
Authorization	string	See authentication.
Content-Type	string	application/json

200 Success

Updated

Note: If no valid fields are provided, returns "Nothing to update".

400 Bad Request

403 Forbidden

404 Not Found

Example - Set Absolute Amount

Example - Adjust Amount

Get Hops

GET https://api.brewfather.app/v2/inventory/hops

This endpoint allows you to list your inventory items. It will only list items you have added manually or edited the default values for, or added an inventory amount on.

Query Parameters

Name	Type	Description
include	array	Array of additional fields to include when complete is false.
complete	boolean	Valid values "True" or "False". Includes all the data in the result if True. Defaults to "False".
inventory_exists	boolean	Valid values "True" or "False". If true, only include items with inventory > 0. Results will be ordered by inventory amount instead of _id.
limit	number	Amount of documents to fetch. Defaults to 10. Max 50.
start_after	string	"_id" of the last item in the previous request
order_by	string	The field to order by, defaults to "_id"
order_by_direction	string	Direction to order result, valid values "asc" for ascending and "desc" for descending. Defaults to "asc"

Headers

Name	Type	Description
Authorization	string	See authentication.

200

[ array of Brewfather JSON ]

Get Hop

GET https://api.brewfather.app/v2/inventory/hops/:id

This endpoint allows you to fetch a specific item.

Query Parameters

Name	Type	Description
include	string	Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

{ Brewfather JSON }

Update Hop

PATCH https://api.brewfather.app/v2/inventory/hops/:id

This endpoint allows you to update the inventory amount of a specific hop.

Requires API scope: inventory.write

Request Body

Name	Type	Description
inventory	number	Set the inventory amount to the given value. Takes precedence over inventory_adjust.
inventory_adjust	number	Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount.

Note: If both inventory and inventory_adjust are provided, inventory takes precedence and inventory_adjust is ignored.

Headers

Name	Type	Description
Authorization	string	See authentication.
Content-Type	string	application/json

200 Success

Updated

Note: If no valid fields are provided, returns "Nothing to update".

400 Bad Request

403 Forbidden

404 Not Found

Example - Set Absolute Amount

Example - Adjust Amount

Get Miscs

GET https://api.brewfather.app/v2/inventory/miscs

This endpoint allows you to list your inventory items. It will only list items you have added manually or edited the default values for, or added an inventory amount on.

Query Parameters

Name	Type	Description
include	array	Array of additional fields to include when complete is false.
complete	boolean	Valid values "True" or "False". Includes all the data in the result if True. Defaults to "False".
inventory_exists	boolean	Valid values "True" or "False". If true, only include items with inventory > 0. Results will be ordered by inventory amount instead of _id.
limit	number	Amount of documents to fetch. Defaults to 10. Max 50.
start_after	string	"_id" of the last item in the previous request
order_by	string	The field to order by, defaults to "_id"
order_by_direction	string	Direction to order result, valid values "asc" for ascending and "desc" for descending. Defaults to "asc"

Headers

Name	Type	Description
Authorization	string	See authentication.

200

[ array of Brewfather JSON ]

Get Misc

GET https://api.brewfather.app/v2/inventory/miscs/:id

This endpoint allows you to fetch a specific item.

Query Parameters

Name	Type	Description
include	string	Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

{ Brewfather JSON }

Update Misc

PATCH https://api.brewfather.app/v2/inventory/miscs/:id

This endpoint allows you to update the inventory amount of a specific misc ingredient.

Requires API scope: inventory.write

Request Body

Name	Type	Description
inventory	number	Set the inventory amount to the given value. Takes precedence over inventory_adjust.
inventory_adjust	number	Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount.

Note: If both inventory and inventory_adjust are provided, inventory takes precedence and inventory_adjust is ignored.

Headers

Name	Type	Description
Authorization	string	See authentication.
Content-Type	string	application/json

200 Success

Updated

Note: If no valid fields are provided, returns "Nothing to update".

400 Bad Request

403 Forbidden

404 Not Found

Example - Set Absolute Amount

Example - Adjust Amount

Get Yeasts

GET https://api.brewfather.app/v2/inventory/yeasts

This endpoint allows you to list your inventory items. It will only list items you have added manually or edited the default values for, or added an inventory amount on.

Query Parameters

Name	Type	Description
include	array	Array of additional fields to include when complete is false.
complete	boolean	Valid values "True" or "False". Includes all the data in the result if True. Defaults to "False".
inventory_exists	boolean	Valid values "True" or "False". If true, only include items with inventory > 0. Results will be ordered by inventory amount instead of _id.
limit	number	Amount of documents to fetch. Defaults to 10. Max 50.
start_after	string	"_id" of the last item in the previous request
order_by	string	The field to order by, defaults to "_id"
order_by_direction	string	Direction to order result, valid values "asc" for ascending and "desc" for descending. Defaults to "asc"

Headers

Name	Type	Description
Authorization	string	See authentication.

200

[ array of Brewfather JSON ]

Get Yeast

GET https://api.brewfather.app/v2/inventory/yeasts/:id

This endpoint allows you to fetch a specific item.

Query Parameters

Name	Type	Description
include	string	Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.

Headers

Name	Type	Description
Authorization	string	See authentication.

200

{ Brewfather JSON }

Update Yeast

PATCH https://api.brewfather.app/v2/inventory/yeasts/:id

This endpoint allows you to update the inventory amount of a specific yeast.

Requires API scope: inventory.write

Request Body

Name	Type	Description
inventory	number	Set the inventory amount to the given value. Takes precedence over inventory_adjust.
inventory_adjust	number	Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount.

Note: If both inventory and inventory_adjust are provided, inventory takes precedence and inventory_adjust is ignored.

Headers

Name	Type	Description
Authorization	string	See authentication.
Content-Type	string	application/json

200 Success

Updated

Note: If no valid fields are provided, returns "Nothing to update".

400 Bad Request

403 Forbidden

404 Not Found

Example - Set Absolute Amount

Example - Adjust Amount