API
Access Brewfather data programmatically using the REST API v2 with batch, recipe, and inventory endpoints.
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 custom ordering of the results
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 Base64 encode: "xyz123:1234567890123456789012345678901234567890abcd"
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
Endpoints for managing brewing batches, readings, and the brew tracker.
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.
Requires API scope: batches.read
Default fields (when complete is false): _id, name, batchNo, status, brewer, brewDate, recipe.name. Use include to request additional fields, or set complete=true for all fields.
Query Parameters
include
string
Comma-separated list 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
Authorization
string
See authentication.
Array of Batch Object
Returned when order_by_direction is not "asc" or "desc".
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the batches.read scope.
Get Batch
GET https://api.brewfather.app/v2/batches/:id
This endpoint allows you to fetch a specific batch.
Requires API scope: batches.read
:id is the _id property from the batch JSON.
Query Parameters
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
Authorization
string
See authentication.
Returned when the batch ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the batches.read scope.
Returned when the batch with the given ID does not exist.
Update Batch
PATCH https://api.brewfather.app/v2/batches/:id
This endpoint allows you to update specific fields of a specific batch. Currently supports 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.
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
Authorization
string
See authentication.
Content-Type
string
application/json
Note: If no valid fields are provided, returns "Nothing to update".
Or
Or
Returned when validation fails or required parameters are missing.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the batches.write scope.
Returned when the batch with the given ID does not exist.
Clear a value:
Get Batch Last Reading
GET https://api.brewfather.app/v2/batches/:id/readings/last
This endpoint allows you to fetch the latest reading received.
Requires API scope: batches.read
:id is the _id property from the batch JSON.
Headers
Authorization
string
See authentication.
Returned when the batch ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the batches.read scope.
Returned when no reading exists for the given batch.
Get Batch All Readings
GET https://api.brewfather.app/v2/batches/: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.
Requires API scope: batches.read
:id is the _id property from the batch JSON.
Headers
Authorization
string
See authentication.
Array of Reading Object
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the batches.read scope.
Get Batch Brew Tracker
GET https://api.brewfather.app/v2/batches/: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.
Requires API scope: batches.read
:id is the _id property from the batch JSON.
Headers
Authorization
string
See authentication.
Returned when the batch ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the batches.read scope.
Returned when the brew tracker for the given batch does not exist.
Recipes
Endpoints for reading recipe data.
Get Recipes
GET https://api.brewfather.app/v2/recipes
This endpoint allows you to list your recipes.
Requires API scope: recipes.read
Default fields (when complete is false): _id, name, author, type, equipment.name, style.name. Use include to request additional fields, or set complete=true for all fields.
Query Parameters
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
Authorization
string
See authentication.
Array of Recipe Object
Returned when order_by_direction is not "asc" or "desc".
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the recipes.read scope.
Get Recipe
GET https://api.brewfather.app/v2/recipes/:id
This endpoint allows you to fetch a specific recipe.
Requires API scope: recipes.read
:id is the _id property from the recipe JSON.
Query Parameters
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
Authorization
string
See authentication.
Returned when the recipe ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the recipes.read scope.
Returned when the recipe with the given ID does not exist.
Inventory
Endpoints for managing inventory items: fermentables, hops, miscellaneous ingredients, and yeasts.
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.
Requires API scope: inventory.read
Default fields (when complete is false): _id, name, inventory, alpha, supplier, type, attenuation, use. Use include to request additional fields, or set complete=true for all fields.
Query Parameters
inventory_negative
boolean
If true, only include items with inventory < 0. Results will be ordered by inventory amount ascending.
include
string
Comma-separated list 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
Authorization
string
See authentication.
Array of Fermentable Object
Returned when order_by_direction is not "asc" or "desc".
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Get Fermentable
GET https://api.brewfather.app/v2/inventory/fermentables/:id
This endpoint allows you to fetch a specific item.
Requires API scope: inventory.read
Query Parameters
include
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Headers
Authorization
string
See authentication.
Returned when the fermentable ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Returned when the fermentable with the given ID does not exist.
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
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
Authorization
string
See authentication.
Content-Type
string
application/json
Note: If no valid fields are provided, returns "Nothing to update".
Returned when the :id parameter is missing.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.write scope.
Returned when the inventory item with the specified ID doesn't exist.
Subtracts 100 grams from current inventory.
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.
Requires API scope: inventory.read
Default fields (when complete is false): _id, name, inventory, alpha, supplier, type, attenuation, use. Use include to request additional fields, or set complete=true for all fields.
Query Parameters
inventory_negative
boolean
If true, only include items with inventory < 0. Results will be ordered by inventory amount ascending.
include
string
Comma-separated list 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
Authorization
string
See authentication.
Array of Hop Object
Returned when order_by_direction is not "asc" or "desc".
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Get Hop
GET https://api.brewfather.app/v2/inventory/hops/:id
This endpoint allows you to fetch a specific item.
Requires API scope: inventory.read
Query Parameters
include
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Headers
Authorization
string
See authentication.
Returned when the hop ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Returned when the hop with the given ID does not exist.
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
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
Authorization
string
See authentication.
Content-Type
string
application/json
Note: If no valid fields are provided, returns "Nothing to update".
Returned when the :id parameter is missing.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.write scope.
Returned when the inventory item with the specified ID doesn't exist.
Subtracts 10 grams from current inventory.
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.
Requires API scope: inventory.read
Default fields (when complete is false): _id, name, inventory, alpha, supplier, type, attenuation, use. Use include to request additional fields, or set complete=true for all fields.
Query Parameters
inventory_negative
boolean
If true, only include items with inventory < 0. Results will be ordered by inventory amount ascending.
include
string
Comma-separated list 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
Authorization
string
See authentication.
Array of Misc Object
Returned when order_by_direction is not "asc" or "desc".
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Get Misc
GET https://api.brewfather.app/v2/inventory/miscs/:id
This endpoint allows you to fetch a specific item.
Requires API scope: inventory.read
Query Parameters
include
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Headers
Authorization
string
See authentication.
Returned when the misc ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Returned when the misc item with the given ID does not exist.
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
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
Authorization
string
See authentication.
Content-Type
string
application/json
Note: If no valid fields are provided, returns "Nothing to update".
Returned when the :id parameter is missing.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.write scope.
Returned when the inventory item with the specified ID doesn't exist.
Adds 10 grams/ml to current inventory.
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.
Requires API scope: inventory.read
Default fields (when complete is false): _id, name, inventory, alpha, supplier, type, attenuation, use. Use include to request additional fields, or set complete=true for all fields.
Query Parameters
inventory_negative
boolean
If true, only include items with inventory < 0. Results will be ordered by inventory amount ascending.
include
string
Comma-separated list 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
Authorization
string
See authentication.
Array of Yeast Object
Returned when order_by_direction is not "asc" or "desc".
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Get Yeast
GET https://api.brewfather.app/v2/inventory/yeasts/:id
This endpoint allows you to fetch a specific item.
Requires API scope: inventory.read
Query Parameters
include
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Headers
Authorization
string
See authentication.
Returned when the yeast ID is not provided.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.read scope.
Returned when the yeast with the given ID does not exist.
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
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
Authorization
string
See authentication.
Content-Type
string
application/json
Note: If no valid fields are provided, returns "Nothing to update".
Returned when the :id parameter is missing.
Returned when the authorization header is missing or invalid.
Returned when the API key lacks the inventory.write scope.
Returned when the inventory item with the specified ID doesn't exist.
Subtracts 1 unit from current inventory.
Reference
Response Types — Complete field documentation for all API response objects
Enum Reference — Valid values for all enum fields
Related docs
Last updated
Was this helpful?