# API (V1)

{% hint style="danger" %}
**API Version 1 is deprecated and will be discontinued soon, please upgrade to version 2**
{% endhint %}

## [Use version 2 of the API](https://docs.brewfather.app/api).

## Disclaimer

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

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

## Authentication

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

**Example**:

UserId: xyz123\
API-key: 1234567890123456789012345678901234567890abcd\
\
Base64 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 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 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". 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**".                                                                          |
| 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 supports 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 %}

## Get Batch Last Reading

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

This endpoint allows you to fetch the latest reading received\
\
\&#xNAN;**:batch\_id** is the **\_id** property from the batch JSON.

#### Headers

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

{% tabs %}
{% tab title="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
}
```

{% endtab %}
{% endtabs %}

## Get Batch All Readings

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/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.\
\
\&#xNAN;**:batch\_id** is the **\_id** property from the batch JSON.

#### Headers

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

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

```
[ array of readings ]
```

{% endtab %}
{% endtabs %}

## Get Batch Brew Tracker

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v1/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.\
\
\&#xNAN;**:batch\_id** is the **\_id** property from the batch JSON.

#### Headers

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

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

```
{ brew tracker object }
```

{% 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". Includes 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                                                                                           |
| ------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| 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**                    |
| 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 an 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". 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**                    |
| 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 an 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". 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**                    |
| 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 an 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". 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**                    |
| 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 an inventory value) |

#### Headers

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

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

```
```

{% endtab %}
{% endtabs %}

## Related docs

* [API](https://docs.brewfather.app/api)