BrewForge Docs

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 isBest for
REST API (this page)Resources under /api/v1: brews, notes, readings, inventory, profiles, custom fieldsSyncing records with another system
Actions APIOne POST /api/v1/actions/{name} per task, covering everything in the app: brew day, cellar, tap lists, orders, preferences, feedback and moreScripts and automations that act like a brewer, references by name
MCP serverThe same actions as tools for AI assistants (Claude, ChatGPT, Cursor, VS Code) at https://brewforge.sh/api/mcp, with OAuth sign-inTalking 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

  1. Get an API token: in BrewForge, go to Settings → Integrations → API tokens and click Create token (see API tokens).
  2. 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 403 with TIER_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) and limit (default 20, max 100) and return a pagination object with page, limit, total, totalPages and hasMore.
  • 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

MethodEndpointDescriptionScope
GET/api/v1/brewsList brews (paginated)brews:read
POST/api/v1/brewsCreate a brewbrews:write
GET/api/v1/brews/:idGet a brewbrews:read
PATCH/api/v1/brews/:idUpdate a brewbrews:write
DELETE/api/v1/brews/:idDelete a brewbrews:write
GET/api/v1/brews/:id/notesList brew notesbrews:read
POST/api/v1/brews/:id/notesAdd a notebrews:write
GET/api/v1/brews/:id/notes/:noteIdGet a notebrews:read
PATCH/api/v1/brews/:id/notes/:noteIdUpdate a notebrews:write
DELETE/api/v1/brews/:id/notes/:noteIdDelete a notebrews:write
GET/api/v1/brews/:id/readingsList fermentation readingsbrews:read
POST/api/v1/brews/:id/readingsAdd a fermentation readingbrews:write
GET/api/v1/brews/:id/custom-fieldsCustom field values of a brewbrews:read

Inventory

:type is one of fermentables, hops, yeasts or miscs.

MethodEndpointDescriptionScope
GET/api/v1/inventoryAll inventory, grouped by typeinventory:read
GET/api/v1/inventory/:typeList items of one type (paginated)inventory:read
POST/api/v1/inventory/:typeCreate an iteminventory:write
GET/api/v1/inventory/:type/:idGet an iteminventory:read
PATCH/api/v1/inventory/:type/:idUpdate an iteminventory:write
DELETE/api/v1/inventory/:type/:idDelete an iteminventory:write

Profiles

MethodEndpointDescriptionScope
GET/api/v1/profiles/equipmentList equipment profilesequipment:read
POST/api/v1/profiles/equipmentCreate an equipment profileequipment:write
GET PATCH DELETE/api/v1/profiles/equipment/:idGet, update or delete an equipment profileequipment:read / equipment:write
GET/api/v1/profiles/stylesList style profilesstyles:read
POST/api/v1/profiles/stylesCreate a style profilestyles:write
GET PATCH DELETE/api/v1/profiles/styles/:idGet, update or delete a style profilestyles:read / styles:write
GET/api/v1/profiles/mash, /api/v1/profiles/mash/:idList or get mash profilesprofiles:read
GET/api/v1/profiles/fermentation, /api/v1/profiles/fermentation/:idList or get fermentation profilesprofiles:read
GET/api/v1/profiles/water, /api/v1/profiles/water/:idList or get water profilesprofiles:read

Custom fields

MethodEndpointDescriptionScope
GET/api/v1/custom-fieldsList custom field definitionscustom-fields:read
GET/api/v1/custom-fields/:idGet a custom field definitioncustom-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.

Next Steps

On this page