> ## Documentation Index
> Fetch the complete documentation index at: https://brewgravity.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> A small REST API over your recipes, brew sessions, fermentation logs, and inventory.

Everything the Brewgravity web app can do with your data, you can do over HTTP. The
API is what the [MCP server](/docs/api-reference/mcp) runs on, and it is stable
enough to script against.

> **Base URL**
>
> ```
> https://brewgravity.com
> ```
>
> All endpoints below are under `/v1`.

## Design

> **Everything is scoped to you**
>
> There is no `user_id` parameter anywhere, because there does not need to be
> one. Your API key identifies you, and every query is scoped to your account
> before it runs. An id belonging to someone else returns `404` — never `403`,
> which would confirm the row exists.

> **Metric, always**
>
> Kilograms, grams, litres, degrees Celsius, minutes. The unit preference in
> the app is a display setting and does not affect the API. Gravity readings
> are specific gravity, with the unit you entered recorded alongside.

> **Children are created against their parent**
>
> A hop is created at `POST /v1/recipes/{recipeId}/hops`, but updated and
> deleted at `/v1/hops/{id}`. Ids are globally unique, so once you have one
> you do not need to remember what it belongs to.

> **Stats are computed, never stored**
>
> `GET /v1/recipes/{id}/stats` recalculates from the current ingredients every
> time. There is no cache to invalidate and no stale number to work around.

## A first request

```bash theme={null}
curl https://brewgravity.com/v1/recipes \
  -H "X-API-Key: $GRAVITY_API_KEY"
```

```json theme={null}
[
  {
    "id": "0f0a1b2c-3d4e-5f60-7182-93a4b5c6d7e8",
    "name": "House IPA",
    "style": "American IPA",
    "type": "all_grain",
    "batch_size_liters": 19,
    "boil_time_minutes": 60,
    "efficiency": 0.72,
    "est_color_srm": 6.4,
    "notes": null,
    "created_at": "2026-03-02T10:11:12.000Z",
    "updated_at": "2026-08-14T18:02:44.000Z"
  }
]
```

## Building a recipe end to end

**1. Create the recipe**

```bash theme={null}
curl -X POST https://brewgravity.com/v1/recipes \
  -H "X-API-Key: $GRAVITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"House IPA","style":"American IPA","batch_size_liters":19,"efficiency":0.72}'
```

Keep the returned `id`.

**2. Add ingredients**

```bash theme={null}
curl -X POST https://brewgravity.com/v1/recipes/$RECIPE_ID/fermentables \
  -H "X-API-Key: $GRAVITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maris Otter","type":"grain","amount_kg":5,"color_srm":3,"yield_percent":81}'

curl -X POST https://brewgravity.com/v1/recipes/$RECIPE_ID/hops \
  -H "X-API-Key: $GRAVITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Citra","amount_grams":28,"alpha_acid":12.5,"time_minutes":60,"use":"boil"}'
```

**3. Check the numbers**

```bash theme={null}
curl https://brewgravity.com/v1/recipes/$RECIPE_ID/stats \
  -H "X-API-Key: $GRAVITY_API_KEY"
```

Returns OG, FG, ABV, IBU, SRM, attenuation, calories, and BU:GU.

**4. Brew it**

```bash theme={null}
curl -X POST https://brewgravity.com/v1/sessions \
  -H "X-API-Key: $GRAVITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"recipe_id\":\"$RECIPE_ID\",\"brew_date\":\"2026-09-01\"}"
```

## What is not in the REST surface

`POST /v1/chat` streams a response and is built for the app's chat panel rather
than for scripting. The threads themselves are ordinary REST resources under
`/v1/chats`, so listing and reading past conversations works normally.

## Next

> **[Authentication](/docs/api-reference/authentication)**
>
> Create an API key and make your first authenticated call.

> **[Errors](/docs/api-reference/errors)**
>
> Status codes, error shapes, and rate limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.