API

REST API

Disclamer

Breaking changes can come at any time as the development of the API is not finalized. Please keep yourself updated on the API-documentation.

Authentication

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/v1/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 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 150 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, response will include a Retry-After header.

Batches

get
Get Batches

https://api.brewfather.app/v1/batches
This endpoint allows you to list your batches. By default it returns batches with status = "Planning". Use the query parameter "status" to query for a given status.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
array
Array of additional fields to include when complete is false. Example "recipe.fermentation,recipe.mash" to include the fermentation and mash profile.
complete
optional
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
optional
string
Valid values "Planning", "Brewing", "Fermenting", "Conditioning", "Completed", "Archived". Defaults to "Planning".
offset
optional
number
Amount of documents to skip. Defaults to 0.
limit
optional
number
Amount of documents to fetch. Defaults to 10. Max 50.
Response
200: OK
[ array of Brewfather BATCH JSON ]

get
Get Batch

https://api.brewfather.app/v1/batches/:id
This endpoint allows you to fetch a specific batch.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
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.
Response
200: OK
{ Brewfather BATCH JSON }

patch
Update Batch

https://api.brewfather.app/v1/batches/:id
This endpoint allows you to update specific fields of a specific batch. Currently support setting the status, please let us know what fields you would like to be able to update via the API.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
status
optional
string
Valid values "Planning", "Brewing", "Fermenting", "Conditioning", "Completed", "Archived".
Response
200: OK

Recipes

get
Get Recipes

https://api.brewfather.app/v1/recipes
This endpoint allows you to list your recipes.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
string
Array of additional fields to include when complete is false. Example "fermentation,mash" to include the fermentation and mash profile.
complete
optional
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.
offset
optional
number
Amount of documents to skip. Defaults to 0.
limit
optional
number
Amount of documents to fetch. Defaults to 10. Max 50.
Response
200: OK
[ array of Brewfather RECIPE JSON ]

get
Get Recipe

https://api.brewfather.app/v1/recipes/:id
This endpoint allows you to fetch a specific recipe.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
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.
Response
200: OK
{ Brewfather RECIPE JSON }

Inventory

get
Get Fermentables

https://api.brewfather.app/v1/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.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
array
Array of additional fields to include when complete is false.
complete
optional
boolean
Valid values "True" or "False". Inlcudes all the data in the result if True. Defaults to "False".
inventory_exists
optional
boolean
Valid valuesValid values "True" or "False". If true, only include items with inventory > 0
offset
optional
number
Amount of documents to skip. Defaults to 0.
limit
optional
number
Amount of documents to fetch. Defaults to 10. Max 50.
Response
200: OK
[ array of Brewfather JSON ]

get
Get Fermentable

https://api.brewfather.app/v1/inventory/fermentables/:id
This endpoint allows you to fetch a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Response
200: OK
{ Brewfather JSON }

patch
Update Fermentable

https://api.brewfather.app/v1/inventory/fermentables/:id
This endpoint allows you to update specific fields of a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
inventory_adjust
optional
number
Adjust the existing inventory amount by the given amount.
inventory
optional
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Response
200: OK

get
Get Hops

https://api.brewfather.app/v1/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.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
array
Array of additional fields to include when complete is false.
complete
optional
boolean
Valid values "True" or "False". Inlcudes all the data in the result if True. Defaults to "False".
inventory_exists
optional
boolean
Valid valuesValid values "True" or "False". If true, only include items with inventory > 0
offset
optional
number
Amount of documents to skip. Defaults to 0.
limit
optional
number
Amount of documents to fetch. Defaults to 10. Max 50.
Response
200: OK
[ array of Brewfather JSON ]

get
Get Hop

https://api.brewfather.app/v1/inventory/hops/:id
This endpoint allows you to fetch a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Response
200: OK
{ Brewfather JSON }

patch
Update Hop

https://api.brewfather.app/v1/inventory/hops/:id
This endpoint allows you to update specific fields of a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
inventory_adjust
optional
number
Adjust the existing inventory amount by the given amount.
inventory
optional
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Response
200: OK

get
Get Miscs

https://api.brewfather.app/v1/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.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
array
Array of additional fields to include when complete is false.
complete
optional
boolean
Valid values "True" or "False". Inlcudes all the data in the result if True. Defaults to "False".
inventory_exists
optional
boolean
Valid valuesValid values "True" or "False". If true, only include items with inventory > 0
offset
optional
number
Amount of documents to skip. Defaults to 0.
limit
optional
number
Amount of documents to fetch. Defaults to 10. Max 50.
Response
200: OK
[ array of Brewfather JSON ]

get
Get Misc

https://api.brewfather.app/v1/inventory/miscs/:id
This endpoint allows you to fetch a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Response
200: OK
{ Brewfather JSON }

patch
Update Misc

https://api.brewfather.app/v1/inventory/miscs/:id
This endpoint allows you to update specific fields of a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
inventory_adjust
optional
number
Adjust the existing inventory amount by the given amount.
inventory
optional
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Response
200: OK

get
Get Yeasts

https://api.brewfather.app/v1/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.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
array
Array of additional fields to include when complete is false.
complete
optional
boolean
Valid values "True" or "False". Inlcudes all the data in the result if True. Defaults to "False".
inventory_exists
optional
boolean
Valid valuesValid values "True" or "False". If true, only include items with inventory > 0
offset
optional
number
Amount of documents to skip. Defaults to 0.
limit
optional
number
Amount of documents to fetch. Defaults to 10. Max 50.
Response
200: OK
[ array of Brewfather JSON ]

get
Get Yeast

https://api.brewfather.app/v1/inventory/yeasts/:id
This endpoint allows you to fetch a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
include
optional
string
Array of fields to include. When omitted all fields are included. Default fields are included in addition to the requested fields.
Response
200: OK
{ Brewfather JSON }

patch
Update Yeast

https://api.brewfather.app/v1/inventory/yeasts/:id
This endpoint allows you to update specific fields of a specific item.
Request
Response
Request
Headers
Authorization
required
string
See authentication.
Query Parameters
inventory_adjust
optional
number
Adjust the existing inventory amount by the given amount.
inventory
optional
number
Set the inventory amount to the given value. (inventory_adjust is ignored if you send in a inventory value)
Response
200: OK