API
REST API version 2
API version 1 is deprecated and will be discontinued, please convert to version 2 (this version).
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/batchesIn 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 form 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
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". Inlcudes 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 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
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.
{ 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.
Query Parameters
status
string
Valid values "Planning", "Brewing", "Fermenting", "Conditioning", "Completed", "Archived".
measuredMashPh
number
Numeric value between 0 and 14
measuredBoilSize
number
Pre-Boil Volume. Value in Liters
measuredFirstWortGravity
number
Pre-Sparge Gravity. Value in SG, example 1.055
measuredPreBoilGravity
number
Pre-Boil Gravity. Value in SG, example 1.055
measuredPostBoilGravity
number
Post Boil Gravity. Value in SG, example 1.055
measuredKettleSize
number
Post-Boil Volume. Value in Liters
measuredOg
number
Original Gravity. Value in SG, example 1.055
measuredFermenterTopUp
number
Fermenter Top-Up. Value in Liters
measuredBatchSize
number
Fermenter Volume. Value in Liters
measuredFg
number
Final Gravity. Value in SG, example 1.011
measuredBottlingSize
number
Final Bottling/Kegging Volume. Value in Liters
carbonationTemp
number
Value in Celcius (°C) between -50°C and 100°C
Headers
Authorization
string
See authentication.
Get Batch Last Reading
GET https://api.brewfather.app/v2/batches/:batch_id/readings/last
This endpoint allows you to fetch the latest reading recieved :batch_id is the _id property from the batch JSON.
Headers
Authorization
string
See authentication.
{
"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
Authorization
string
See authentication.
[ 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
Authorization
string
See authentication.
{ brew tracker object }Recipes
Get Recipes
GET https://api.brewfather.app/v2/recipes
This endpoint allows you to list your recipes.
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". Inlcudes 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 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
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.
{ 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
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". Inlcudes 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 Brewfather JSON ]Get Fermentable
GET https://api.brewfather.app/v2/inventory/fermentables/:id
This endpoint allows you to fetch a specific item.
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.
{ Brewfather JSON }Update Fermentable
PATCH https://api.brewfather.app/v2/inventory/fermentables/:id
This endpoint allows you to update specific fields of a specific item.
Query Parameters
inventory_adjust
number
Adjust the existing inventory amount by the given amount.
inventory
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Headers
Authorization
string
See authentication.
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
include
array
Array of additional fields to include when complete is false.
complete
boolean
Valid values "True" or "False". Inlcudes 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 Brewfather JSON ]Get Hop
GET https://api.brewfather.app/v2/inventory/hops/:id
This endpoint allows you to fetch a specific item.
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.
{ Brewfather JSON }Update Hop
PATCH https://api.brewfather.app/v2/inventory/hops/:id
This endpoint allows you to update specific fields of a specific item.
Query Parameters
inventory_adjust
number
Adjust the existing inventory amount by the given amount.
inventory
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Headers
Authorization
string
See authentication.
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
include
array
Array of additional fields to include when complete is false.
complete
boolean
Valid values "True" or "False". Inlcudes 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 Brewfather JSON ]Get Misc
GET https://api.brewfather.app/v2/inventory/miscs/:id
This endpoint allows you to fetch a specific item.
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.
{ Brewfather JSON }Update Misc
PATCH https://api.brewfather.app/v2/inventory/miscs/:id
This endpoint allows you to update specific fields of a specific item.
Query Parameters
inventory_adjust
number
Adjust the existing inventory amount by the given amount.
inventory
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Headers
Authorization
string
See authentication.
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
include
array
Array of additional fields to include when complete is false.
complete
boolean
Valid values "True" or "False". Inlcudes 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 Brewfather JSON ]Get Yeast
GET https://api.brewfather.app/v2/inventory/yeasts/:id
This endpoint allows you to fetch a specific item.
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.
{ Brewfather JSON }Update Yeast
PATCH https://api.brewfather.app/v2/inventory/yeasts/:id
This endpoint allows you to update specific fields of a specific item.
Query Parameters
inventory_adjust
number
Adjust the existing inventory amount by the given amount.
inventory
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Headers
Authorization
string
See authentication.
Last updated
Was this helpful?