> For the complete documentation index, see [llms.txt](https://docs.brewfather.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.brewfather.app/api.md).

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

| Scope              | Permission       |
| ------------------ | ---------------- |
| `recipes.read`     | Read Recipes     |
| `recipes.write`    | Edit Recipes     |
| `recipes.delete`   | Delete Recipes   |
| `batches.read`     | Read Batches     |
| `batches.write`    | Edit Batches     |
| `batches.delete`   | Delete Batches   |
| `inventory.read`   | Read Inventory   |
| `inventory.write`  | Edit Inventory   |
| `inventory.delete` | Delete 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](/api/types.md#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](/api/types.md#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 %}

## Delete Batch

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

This endpoint allows you to delete a specific batch.

**Requires API scope**: `batches.delete`

**:id** is the **\_id** property from the batch JSON.

#### Headers

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

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

```
Deleted
```

{% 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.delete` scope.
{% endtab %}

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

```
Not Found
```

Returned when the batch with the given ID does not exist.
{% endtab %}

{% tab title="Example" %}

```bash
curl -X DELETE "https://api.brewfather.app/v2/batches/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS"
```

{% 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](/api/types.md#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](/api/types.md#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 and managing 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](/api/types.md#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](/api/types.md#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 %}

## Create Recipe

<mark style="color:green;">`POST`</mark> `https://api.brewfather.app/v2/recipes`

This endpoint allows you to create a recipe.

**Requires API scope**: `recipes.write`

#### Request Body

Send a JSON body compatible with the [Recipe Object](/api/types.md#recipe-object). Server-owned root fields are ignored or overwritten, including `_id`, `_uid`, `_rev`, `_type`, `_timestamp`, `_timestamp_ms`, `_created`, `_app_metadata`, `createdAt`, and `data`.

New recipes are created as private recipes and receive server-generated IDs, revision values, timestamps, and app metadata.

#### Headers

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

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

```json
{
  "id": "RECIPE_ID"
}
```

{% endtab %}

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

```
Missing body
```

Or validation errors for invalid recipe fields.
{% 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.write` scope.
{% endtab %}

{% tab title="Example" %}

```bash
curl -X POST "https://api.brewfather.app/v2/recipes" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"name":"API Pale Ale","type":"All Grain","style":{"name":"American Pale Ale"}}'
```

{% endtab %}
{% endtabs %}

## Update Recipe

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

This endpoint allows you to update supplied fields of a specific recipe.

**Requires API scope**: `recipes.write`

**:id** is the **\_id** property from the recipe JSON.

#### Request Body

Send only the fields you want to update. The request body is merged with the existing recipe and then validated as a [Recipe Object](/api/types.md#recipe-object). Server-owned root fields are ignored or overwritten, including `_id`, `_uid`, `_rev`, `_type`, `_timestamp`, `_timestamp_ms`, `_created`, `_app_metadata`, `createdAt`, and `data`.

#### Headers

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

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

```
Updated
```

{% endtab %}

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

```
Missing ID
```

Or

```
Missing body
```

Or validation errors for invalid recipe fields.
{% 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.write` scope.
{% endtab %}

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

```
Not Found
```

Returned when the recipe with the given ID does not exist.
{% endtab %}

{% tab title="Example" %}

```bash
curl -X PATCH "https://api.brewfather.app/v2/recipes/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated API Pale Ale"}'
```

{% endtab %}
{% endtabs %}

## Delete Recipe

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

This endpoint allows you to delete a specific recipe.

**Requires API scope**: `recipes.delete`

**:id** is the **\_id** property from the recipe JSON.

#### Headers

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

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

```
Deleted
```

{% 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.delete` scope.
{% endtab %}

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

```
Not Found
```

Returned when the recipe with the given ID does not exist.
{% endtab %}

{% tab title="Example" %}

```bash
curl -X DELETE "https://api.brewfather.app/v2/recipes/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS"
```

{% endtab %}
{% endtabs %}

## Inventory

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

The write endpoints below use the same collection names as the read endpoints:

| Collection     | Object type                                            |
| -------------- | ------------------------------------------------------ |
| `fermentables` | [Fermentable Object](/api/types.md#fermentable-object) |
| `hops`         | [Hop Object](/api/types.md#hop-object)                 |
| `miscs`        | [Misc Object](/api/types.md#misc-object)               |
| `yeasts`       | [Yeast Object](/api/types.md#yeast-object)             |

## Create Inventory Item

<mark style="color:green;">`POST`</mark> `https://api.brewfather.app/v2/inventory/:collection`

This endpoint allows you to create an inventory item in `fermentables`, `hops`, `miscs`, or `yeasts`.

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

#### Request Body

Send a JSON body compatible with the object type for the selected collection. Root fields beginning with `_` and `createdAt` are ignored or overwritten by the server.

New inventory items receive server-generated IDs, revision values, and timestamps. If omitted, `inventory` is set to `null` and `hidden` is set to `false`.

#### Headers

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

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

```json
{
  "id": "INVENTORY_ITEM_ID"
}
```

{% endtab %}

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

```
Missing body
```

Or validation errors for invalid item fields.
{% 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="Example" %}

```bash
curl -X POST "https://api.brewfather.app/v2/inventory/fermentables" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{"name":"API Pale Malt","type":"Grain","supplier":"Brewfather","inventory":1000}'
```

{% endtab %}
{% endtabs %}

## Update Inventory Item

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

This endpoint allows you to update the inventory amount or supplied fields of a specific inventory item.

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

**:id** is the **\_id** property from the inventory item JSON.

#### Request Body

Send only the fields you want to update. You can update any supported field for the selected object type.

| Name              | Type           | Description                                                                                           |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| inventory         | number\|string | Set the inventory amount to the given value. Takes precedence over `inventory_adjust`.                |
| inventory\_adjust | number\|string | Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount. |

**Note**: `inventory` and `inventory_adjust` must be finite numeric values. Partial numeric strings such as `5kg` are rejected. If both are provided, `inventory` takes precedence and `inventory_adjust` is ignored. `inventory_adjust` is an instruction and is never stored as a document field.

Root fields beginning with `_` and `createdAt` are ignored. The server updates revision and timestamp fields automatically.

#### Headers

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

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

```
Updated
```

{% endtab %}

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

```
Missing ID
```

Or

```
Missing body
```

Or

```
Invalid inventory
```

Or

```
Invalid inventory_adjust
```

Or validation errors for invalid item fields.
{% 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 %}

{% tab title="Example - Update Fields" %}

```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 '{"name":"Updated Pale Malt","supplier":"Brewfather","inventory":750}'
```

{% endtab %}
{% endtabs %}

## Delete Inventory Item

<mark style="color:red;">`DELETE`</mark> `https://api.brewfather.app/v2/inventory/:collection/:id`

This endpoint allows you to delete a specific inventory item.

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

**:id** is the **\_id** property from the inventory item JSON.

When deleting a default inventory item, Brewfather records the deletion so the default item is not recreated automatically.

#### Headers

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

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

```
Deleted
```

{% endtab %}

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

```
Missing ID
```

Returned when the inventory item 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.delete` 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" %}

```bash
curl -X DELETE "https://api.brewfather.app/v2/inventory/fermentables/:id" \
  -H "authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS"
```

{% endtab %}
{% endtabs %}

## 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](/api/types.md#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](/api/types.md#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 or supplied fields of a specific fermentable.

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

#### Request Body

| Name              | Type           | Description                                                                                           |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| inventory         | number\|string | Set the inventory amount to the given value. Takes precedence over `inventory_adjust`.                |
| inventory\_adjust | number\|string | Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount. |

**Note**: You can also send supported fermentable fields. `inventory` and `inventory_adjust` must be finite numeric values. If both 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
```

Or

```
Invalid inventory
```

Or

```
Invalid inventory_adjust
```

Or validation errors for invalid fermentable fields.
{% 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](/api/types.md#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](/api/types.md#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 or supplied fields of a specific hop.

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

#### Request Body

| Name              | Type           | Description                                                                                           |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| inventory         | number\|string | Set the inventory amount to the given value. Takes precedence over `inventory_adjust`.                |
| inventory\_adjust | number\|string | Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount. |

**Note**: You can also send supported hop fields. `inventory` and `inventory_adjust` must be finite numeric values. If both 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
```

Or

```
Invalid inventory
```

Or

```
Invalid inventory_adjust
```

Or validation errors for invalid hop fields.
{% 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](/api/types.md#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](/api/types.md#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 or supplied fields of a specific misc ingredient.

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

#### Request Body

| Name              | Type           | Description                                                                                           |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| inventory         | number\|string | Set the inventory amount to the given value. Takes precedence over `inventory_adjust`.                |
| inventory\_adjust | number\|string | Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount. |

**Note**: You can also send supported misc fields. `inventory` and `inventory_adjust` must be finite numeric values. If both 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
```

Or

```
Invalid inventory
```

Or

```
Invalid inventory_adjust
```

Or validation errors for invalid misc fields.
{% 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](/api/types.md#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](/api/types.md#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 or supplied fields of a specific yeast.

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

#### Request Body

| Name              | Type           | Description                                                                                           |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| inventory         | number\|string | Set the inventory amount to the given value. Takes precedence over `inventory_adjust`.                |
| inventory\_adjust | number\|string | Adjust the existing inventory amount by adding (positive) or subtracting (negative) the given amount. |

**Note**: You can also send supported yeast fields. `inventory` and `inventory_adjust` must be finite numeric values. If both 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
```

Or

```
Invalid inventory
```

Or

```
Invalid inventory_adjust
```

Or validation errors for invalid yeast fields.
{% 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](/api/types.md) — Complete field documentation for all API response objects
* [Enum Reference](/api/enums.md) — Valid values for all enum fields

## Related docs

* [API Types](/api/types.md)
* [API Enums](/api/enums.md)
* [Connected Apps](/connected-apps.md)
* [Webhooks](/webhooks.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.brewfather.app/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.