# API

{% hint style="warning" %}
API version 1 is deprecated and will be discontinued; please convert to version 2 (this version).
{% endhint %}

{% hint style="info" %}
**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
  {% endhint %}

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

```javascript
curl -H "authorization: Basic eHl6MTIzOjEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTBhYmNk" \
https://api.brewfather.app/v2/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 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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header.

## Batches

Endpoints for managing brewing batches, readings, and the brew tracker.

## Get Batches

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

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

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

{% tabs %}
{% tab title="200 " %}
Array of [Batch Object](https://docs.brewfather.app/types#batch-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Invalid order by direction
```

Returned when `order_by_direction` is not "asc" or "desc".
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `batches.read` scope.
{% endtab %}
{% endtabs %}

## Get Batch

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

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

#### Query Parameters

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

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

{% tabs %}
{% tab title="200 " %}
[Batch Object](https://docs.brewfather.app/types#batch-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the batch ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `batches.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the batch with the given ID does not exist.
{% endtab %}
{% endtabs %}

## Update Batch

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

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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |
| Content-Type  | string | application/json    |

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

```
Updated
```

**Note**: If no valid fields are provided, returns `"Nothing to update"`.
{% endtab %}

{% tab title="400 Bad Request" %}

```
Invalid status
```

Or

```
Invalid {field_name}
```

Or

```
Missing ID
```

Returned when validation fails or required parameters are missing.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `batches.write` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the batch with the given ID does not exist.
{% endtab %}

{% tab title="Example" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/batches/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"status":"Fermenting","measuredOg":1.050,"measuredFg":1.012}'
```

**Clear a value:**

```bash
curl -X PATCH "https://api.brewfather.app/v2/batches/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"measuredOg":null}'
```

{% endtab %}
{% endtabs %}

## Get Batch Last Reading

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

This endpoint allows you to fetch the latest reading received.\
\
**Requires API scope**: `batches.read`\
\
\&#xNAN;**: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 %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the batch ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `batches.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when no reading exists for the given batch.
{% endtab %}
{% endtabs %}

## Get Batch All Readings

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

#### Headers

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

{% tabs %}
{% tab title="200 " %}
Array of [Reading Object](https://docs.brewfather.app/types#reading-object)
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `batches.read` scope.
{% endtab %}
{% endtabs %}

## Get Batch Brew Tracker

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

#### Headers

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

{% tabs %}
{% tab title="200 " %}
[Brew Tracker Object](https://docs.brewfather.app/types#brew-tracker-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the batch ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `batches.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the brew tracker for the given batch does not exist.
{% endtab %}
{% endtabs %}

## Recipes

Endpoints for reading recipe data.

## Get Recipes

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

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

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

{% tabs %}
{% tab title="200 " %}
Array of [Recipe Object](https://docs.brewfather.app/types#recipe-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Invalid order by direction
```

Returned when `order_by_direction` is not "asc" or "desc".
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `recipes.read` scope.
{% endtab %}
{% endtabs %}

## Get Recipe

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

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

#### Query Parameters

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

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

{% tabs %}
{% tab title="200 " %}
[Recipe Object](https://docs.brewfather.app/types#recipe-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the recipe ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `recipes.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the recipe with the given ID does not exist.
{% endtab %}
{% endtabs %}

## Inventory

Endpoints for managing inventory items: fermentables, hops, miscellaneous ingredients, and yeasts.

## Get Fermentables

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

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

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

{% tabs %}
{% tab title="200 " %}
Array of [Fermentable Object](https://docs.brewfather.app/types#fermentable-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Invalid order by direction
```

Returned when `order_by_direction` is not "asc" or "desc".
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}
{% endtabs %}

## Get Fermentable

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v2/inventory/fermentables/:id`

This endpoint allows you to fetch a specific item.

**Requires API scope**: `inventory.read`

#### 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 " %}
[Fermentable Object](https://docs.brewfather.app/types#fermentable-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the fermentable ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the fermentable with the given ID does not exist.
{% endtab %}
{% endtabs %}

## Update Fermentable

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

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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |
| Content-Type  | string | application/json    |

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

```
Updated
```

**Note**: If no valid fields are provided, returns `"Nothing to update"`.
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the `:id` parameter is missing.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.write` scope.
{% endtab %}

{% tab title="404 Not Found" %}

```
Not Found
```

Returned when the inventory item with the specified ID doesn't exist.
{% endtab %}

{% tab title="Example - Set Absolute Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/fermentables/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory":500}'
```

{% endtab %}

{% tab title="Example - Adjust Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/fermentables/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory_adjust":-100}'
```

Subtracts 100 grams from current inventory.
{% endtab %}
{% endtabs %}

## Get Hops

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

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

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

{% tabs %}
{% tab title="200 " %}
Array of [Hop Object](https://docs.brewfather.app/types#hop-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Invalid order by direction
```

Returned when `order_by_direction` is not "asc" or "desc".
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}
{% endtabs %}

## Get Hop

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v2/inventory/hops/:id`

This endpoint allows you to fetch a specific item.

**Requires API scope**: `inventory.read`

#### 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 " %}
[Hop Object](https://docs.brewfather.app/types#hop-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the hop ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the hop with the given ID does not exist.
{% endtab %}
{% endtabs %}

## Update Hop

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

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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |
| Content-Type  | string | application/json    |

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

```
Updated
```

**Note**: If no valid fields are provided, returns `"Nothing to update"`.
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the `:id` parameter is missing.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.write` scope.
{% endtab %}

{% tab title="404 Not Found" %}

```
Not Found
```

Returned when the inventory item with the specified ID doesn't exist.
{% endtab %}

{% tab title="Example - Set Absolute Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/hops/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory":100}'
```

{% endtab %}

{% tab title="Example - Adjust Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/hops/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory_adjust":-10}'
```

Subtracts 10 grams from current inventory.
{% endtab %}
{% endtabs %}

## Get Miscs

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

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

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

{% tabs %}
{% tab title="200 " %}
Array of [Misc Object](https://docs.brewfather.app/types#misc-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Invalid order by direction
```

Returned when `order_by_direction` is not "asc" or "desc".
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}
{% endtabs %}

## Get Misc

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v2/inventory/miscs/:id`

This endpoint allows you to fetch a specific item.

**Requires API scope**: `inventory.read`

#### 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 " %}
[Misc Object](https://docs.brewfather.app/types#misc-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the misc ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the misc item with the given ID does not exist.
{% endtab %}
{% endtabs %}

## Update Misc

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

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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |
| Content-Type  | string | application/json    |

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

```
Updated
```

**Note**: If no valid fields are provided, returns `"Nothing to update"`.
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the `:id` parameter is missing.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.write` scope.
{% endtab %}

{% tab title="404 Not Found" %}

```
Not Found
```

Returned when the inventory item with the specified ID doesn't exist.
{% endtab %}

{% tab title="Example - Set Absolute Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/miscs/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory":50}'
```

{% endtab %}

{% tab title="Example - Adjust Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/miscs/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory_adjust":10}'
```

Adds 10 grams/ml to current inventory.
{% endtab %}
{% endtabs %}

## Get Yeasts

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

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

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

{% tabs %}
{% tab title="200 " %}
Array of [Yeast Object](https://docs.brewfather.app/types#yeast-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Invalid order by direction
```

Returned when `order_by_direction` is not "asc" or "desc".
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}
{% endtabs %}

## Get Yeast

<mark style="color:blue;">`GET`</mark> `https://api.brewfather.app/v2/inventory/yeasts/:id`

This endpoint allows you to fetch a specific item.

**Requires API scope**: `inventory.read`

#### 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 " %}
[Yeast Object](https://docs.brewfather.app/types#yeast-object)
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the yeast ID is not provided.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.read` scope.
{% endtab %}

{% tab title="404 Not Found" %}
Returned when the yeast with the given ID does not exist.
{% endtab %}
{% endtabs %}

## Update Yeast

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

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

| Name          | Type   | Description         |
| ------------- | ------ | ------------------- |
| Authorization | string | See authentication. |
| Content-Type  | string | application/json    |

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

```
Updated
```

**Note**: If no valid fields are provided, returns `"Nothing to update"`.
{% endtab %}

{% tab title="400 Bad Request" %}

```
Missing ID
```

Returned when the `:id` parameter is missing.
{% endtab %}

{% tab title="401 Unauthorized" %}

```
Unauthorized
```

Returned when the authorization header is missing or invalid.
{% endtab %}

{% tab title="403 Forbidden" %}

```
Forbidden
```

Returned when the API key lacks the `inventory.write` scope.
{% endtab %}

{% tab title="404 Not Found" %}

```
Not Found
```

Returned when the inventory item with the specified ID doesn't exist.
{% endtab %}

{% tab title="Example - Set Absolute Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/yeasts/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory":5}'
```

{% endtab %}

{% tab title="Example - Adjust Amount" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/inventory/yeasts/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"inventory_adjust":-1}'
```

Subtracts 1 unit from current inventory.
{% endtab %}
{% endtabs %}

***

## Reference

* [Response Types](https://docs.brewfather.app/api/types) — Complete field documentation for all API response objects
* [Enum Reference](https://docs.brewfather.app/api/enums) — Valid values for all enum fields

## Related docs

* [API Types](https://docs.brewfather.app/api/types)
* [API Enums](https://docs.brewfather.app/api/enums)
* [Connected Apps](https://docs.brewfather.app/connected-apps)
* [Webhooks](https://docs.brewfather.app/webhooks)