# 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"

```javascript
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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header.

## Batches

## Get Batches

<mark style="color:blue;">`GET`</mark> `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.

#### Query Parameters

| Name     | Type    | Description                                                                                                                                                                                 |
| -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| include  | array   | Array of additional fields to include when complete is false. Example "recipe.fermentatio&#x6E;**,**&#x72;ecipe.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**". Defaults to "**Planning**".                                              |
| offset   | number  | Amount of documents to skip. Defaults to **0**.                                                                                                                                             |
| limit    | number  | Amount of documents to fetch. Defaults to **10**. Max **50**.                                                                                                                               |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
[ array of Brewfather BATCH JSON ]
```

{% endtab %}
{% endtabs %}

## Get Batch

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/batches/:id`

This endpoint allows you to fetch a specific batch.\
\
\&#xNAN;**:id** is the **\_id** property from the batch JSON.

#### Query Parameters

| Name    | Type   | Description                                                                                                                                                                                                                              |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| include | string | Array of fields to include. Example "recipe.fermentatio&#x6E;**,**&#x72;ecipe.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. |

{% tabs %}
{% tab title="200 " %}

```
{ Brewfather BATCH JSON }
```

{% endtab %}
{% endtabs %}

## Update Batch

<mark style="color:purple;">`PATCH`</mark> `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.

#### Query Parameters

| Name   | Type   | Description                                                                                                        |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------ |
| status | string | Valid values "**Planning**", "**Brewing**", "**Fermenting**", "**Conditioning**", "**Completed**", "**Archived**". |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Recipes

## Get Recipes

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/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 "fermentatio&#x6E;**,**&#x6D;ash" 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. |
| offset   | number  | Amount of documents to skip. Defaults to **0**.                                                                                                             |
| limit    | number  | Amount of documents to fetch. Defaults to **10**. Max **50**.                                                                                               |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
[ array of Brewfather RECIPE JSON ]
```

{% endtab %}
{% endtabs %}

## Get Recipe

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/recipes/:id`

This endpoint allows you to fetch a specific recipe.\
\
\&#xNAN;**:id** is the **\_id** property from the recipe JSON.

#### Query Parameters

| Name    | Type   | Description                                                                                                                                                                                                                           |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| include | string | Array of additional fields to include. Example "fermentatio&#x6E;**,**&#x6D;ash" 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. |

{% tabs %}
{% tab title="200 " %}

```
{ Brewfather RECIPE JSON }
```

{% endtab %}
{% endtabs %}

## Inventory

## Get Fermentables

<mark style="color:blue;">`GET`</mark> `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.

#### Query Parameters

| Name              | Type    | Description                                                                                           |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| 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 valuesValid values "True" or "False". If true, only include items with inventory **> 0**        |
| offset            | number  | Amount of documents to skip. Defaults to **0**.                                                       |
| limit             | number  | Amount of documents to fetch. Defaults to **10**. Max **50**.                                         |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
[ array of Brewfather JSON ]
```

{% endtab %}
{% endtabs %}

## Get Fermentable

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/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. |

{% tabs %}
{% tab title="200 " %}

```
{ Brewfather JSON }
```

{% endtab %}
{% endtabs %}

## Update Fermentable

<mark style="color:purple;">`PATCH`</mark> `https://api.brewfather.app/v1/inventory/fermentables/:id`

This endpoint allows you to update specific fields of a specific item.

#### Query Parameters

| Name              | Type   | Description                                                                                                  |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| 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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get Hops

<mark style="color:blue;">`GET`</mark> `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.

#### Query Parameters

| Name              | Type    | Description                                                                                           |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| 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 valuesValid values "True" or "False". If true, only include items with inventory **> 0**        |
| offset            | number  | Amount of documents to skip. Defaults to **0**.                                                       |
| limit             | number  | Amount of documents to fetch. Defaults to **10**. Max **50**.                                         |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
[ array of Brewfather JSON ]
```

{% endtab %}
{% endtabs %}

## Get Hop

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/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. |

{% tabs %}
{% tab title="200 " %}

```
{ Brewfather JSON }
```

{% endtab %}
{% endtabs %}

## Update Hop

<mark style="color:purple;">`PATCH`</mark> `https://api.brewfather.app/v1/inventory/hops/:id`

This endpoint allows you to update specific fields of a specific item.

#### Query Parameters

| Name              | Type   | Description                                                                                                  |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| 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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get Miscs

<mark style="color:blue;">`GET`</mark> `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.

#### Query Parameters

| Name              | Type    | Description                                                                                           |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| 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 valuesValid values "True" or "False". If true, only include items with inventory **> 0**        |
| offset            | number  | Amount of documents to skip. Defaults to **0**.                                                       |
| limit             | number  | Amount of documents to fetch. Defaults to **10**. Max **50**.                                         |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
[ array of Brewfather JSON ]
```

{% endtab %}
{% endtabs %}

## Get Misc

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/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. |

{% tabs %}
{% tab title="200 " %}

```
{ Brewfather JSON }
```

{% endtab %}
{% endtabs %}

## Update Misc

<mark style="color:purple;">`PATCH`</mark> `https://api.brewfather.app/v1/inventory/miscs/:id`

This endpoint allows you to update specific fields of a specific item.

#### Query Parameters

| Name              | Type   | Description                                                                                                  |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| 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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get Yeasts

<mark style="color:blue;">`GET`</mark> `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.

#### Query Parameters

| Name              | Type    | Description                                                                                           |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| 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 valuesValid values "True" or "False". If true, only include items with inventory **> 0**        |
| offset            | number  | Amount of documents to skip. Defaults to **0**.                                                       |
| limit             | number  | Amount of documents to fetch. Defaults to **10**. Max **50**.                                         |

#### Headers

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
[ array of Brewfather JSON ]
```

{% endtab %}
{% endtabs %}

## Get Yeast

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/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. |

{% tabs %}
{% tab title="200 " %}

```
{ Brewfather JSON }
```

{% endtab %}
{% endtabs %}

## Update Yeast

<mark style="color:purple;">`PATCH`</mark> `https://api.brewfather.app/v1/inventory/yeasts/:id`

This endpoint allows you to update specific fields of a specific item.

#### Query Parameters

| Name              | Type   | Description                                                                                                  |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| 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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}