API Overview
Public API documentation for BrewForge brewing software: the REST API, the actions API and the MCP server for AI assistants
The BrewForge REST API lets your scripts and other apps read and change your brewing data: brews with notes and fermentation readings, inventory, profiles and custom fields.
Three ways in
| What it is | Best for | |
|---|---|---|
| REST API (this page) | Resources under /api/v1: brews, notes, readings, inventory, profiles, custom fields | Syncing records with another system |
| Actions API | One POST /api/v1/actions/{name} per task, covering everything in the app: brew day, cellar, tap lists, orders, preferences, feedback and more | Scripts and automations that act like a brewer, references by name |
| MCP server | The same actions as tools for AI assistants (Claude, ChatGPT, Cursor, VS Code) at https://brewforge.sh/api/mcp, with OAuth sign-in | Talking to your brewery data in an AI assistant |
All three use the same API tokens and need the Pro plan. The tool reference lists every action.
Quick Start
- Get an API token: in BrewForge, go to Settings → Integrations → API tokens and click Create token (see API tokens).
- Make your first request:
curl https://brewforge.sh/api/v1/brews \
-H "Authorization: Bearer bfk_your_token_here"Brewing math without an account
The calculators (ABV, IBU, strike water, priming sugar, …) are a separate, free API that needs no token: see the Calculator API.
Requirements
- Pro plan or higher (Pro, AI or Commercial). Free and Basic accounts get a
403withTIER_REQUIRED. - An API token with the scopes the endpoints need.
Basics
- Base URL:
https://brewforge.sh/api/v1 - Format: JSON in and out. Errors come as
{ "error": { "code", "message", "details" } }. - Pagination: list endpoints take
page(from 1) andlimit(default 20, max 100) and return apaginationobject withpage,limit,total,totalPagesandhasMore. - Limits: 100 requests per hour and 1,000 per 30 days per account, see Rate Limits. The actions API and MCP server have their own, higher limit.
Available Endpoints
Brews
| Method | Endpoint | Description | Scope |
|---|---|---|---|
GET | /api/v1/brews | List brews (paginated) | brews:read |
POST | /api/v1/brews | Create a brew | brews:write |
GET | /api/v1/brews/:id | Get a brew | brews:read |
PATCH | /api/v1/brews/:id | Update a brew | brews:write |
DELETE | /api/v1/brews/:id | Delete a brew | brews:write |
GET | /api/v1/brews/:id/notes | List brew notes | brews:read |
POST | /api/v1/brews/:id/notes | Add a note | brews:write |
GET | /api/v1/brews/:id/notes/:noteId | Get a note | brews:read |
PATCH | /api/v1/brews/:id/notes/:noteId | Update a note | brews:write |
DELETE | /api/v1/brews/:id/notes/:noteId | Delete a note | brews:write |
GET | /api/v1/brews/:id/readings | List fermentation readings | brews:read |
POST | /api/v1/brews/:id/readings | Add a fermentation reading | brews:write |
GET | /api/v1/brews/:id/custom-fields | Custom field values of a brew | brews:read |
Inventory
:type is one of fermentables, hops, yeasts or miscs.
| Method | Endpoint | Description | Scope |
|---|---|---|---|
GET | /api/v1/inventory | All inventory, grouped by type | inventory:read |
GET | /api/v1/inventory/:type | List items of one type (paginated) | inventory:read |
POST | /api/v1/inventory/:type | Create an item | inventory:write |
GET | /api/v1/inventory/:type/:id | Get an item | inventory:read |
PATCH | /api/v1/inventory/:type/:id | Update an item | inventory:write |
DELETE | /api/v1/inventory/:type/:id | Delete an item | inventory:write |
Profiles
| Method | Endpoint | Description | Scope |
|---|---|---|---|
GET | /api/v1/profiles/equipment | List equipment profiles | equipment:read |
POST | /api/v1/profiles/equipment | Create an equipment profile | equipment:write |
GET PATCH DELETE | /api/v1/profiles/equipment/:id | Get, update or delete an equipment profile | equipment:read / equipment:write |
GET | /api/v1/profiles/styles | List style profiles | styles:read |
POST | /api/v1/profiles/styles | Create a style profile | styles:write |
GET PATCH DELETE | /api/v1/profiles/styles/:id | Get, update or delete a style profile | styles:read / styles:write |
GET | /api/v1/profiles/mash, /api/v1/profiles/mash/:id | List or get mash profiles | profiles:read |
GET | /api/v1/profiles/fermentation, /api/v1/profiles/fermentation/:id | List or get fermentation profiles | profiles:read |
GET | /api/v1/profiles/water, /api/v1/profiles/water/:id | List or get water profiles | profiles:read |
Custom fields
| Method | Endpoint | Description | Scope |
|---|---|---|---|
GET | /api/v1/custom-fields | List custom field definitions | custom-fields:read |
GET | /api/v1/custom-fields/:id | Get a custom field definition | custom-fields:read |
OpenAPI Spec
The full API, REST endpoints and actions, is described by an OpenAPI 3 document at docs.brewforge.sh/openapi.json. Use it to generate clients or to give AI agents and tools a machine-readable view of every endpoint. Actions are tagged Actions: <toolset>. The scopes a token can have are also listed at https://brewforge.sh/.well-known/oauth-protected-resource.