Actions API
The BrewForge actions API: task-shaped actions like log_fermentation_reading or package_beer over HTTP, with discovery, references by name, canonical units, confirmations for deletes and teaching errors.
The actions API gives you one HTTP endpoint per thing a brewer does: find brews, log a fermentation reading, package a beer, record what's on tap, find out what you're short of. Each action is a POST with a small JSON body:
curl -X POST https://brewforge.sh/api/v1/actions/log_fermentation_reading \
-H "Authorization: Bearer bfk_your_token_here" \
-H "Content-Type: application/json" \
-d '{"brew": "Citra Pale Ale", "gravity": 3.1, "gravity_unit": "plato", "temp": 19.5}'{
"brew": { "id": "f3a624c7-…", "name": "Citra Pale Ale", "status": "fermenting" },
"reading": { "id": "a93802cd-…", "at": "2026-11-11T15:29:43.928Z", "gravity_sg": 1.012, "temp_c": 19.5 },
"readings_count": 24
}The same actions are the tools of the MCP server, with the same names, parameters and results. The tool reference lists every action.
Actions or REST?
BrewForge has two APIs side by side, with the same tokens:
REST API (/api/v1/brews, /api/v1/inventory, …) | Actions API (/api/v1/actions/…) | |
|---|---|---|
| Shape | Resources: list, get, create, update, delete records | Tasks: one action per thing you do in the app |
| Covers | Brews, notes, readings, inventory, profiles, custom fields | Everything in the app except account security, payments and admin |
| References | Ids | Ids or names ("Citra Pale Ale", batch "#12") |
| Results | Full records | Compact rows; heavy sections on request |
| Best for | Syncing records with another system | Scripts, automations and AI agents that act like a brewer |
| Limit | 100 per hour, 1,000 per 30 days | 600 per hour, 20,000 per 30 days |
The REST API stays as it is (overview). Use the actions API for anything the REST API doesn't cover, or when you'd otherwise chain several REST calls.
Requirements
- Pro plan or higher. Other plans get
TIER_REQUIRED. Some actions also need a plan feature (cellar, tap lists, labels, …); the tool reference names it. - A token: an API token (
bfk_…) or an OAuth access token of a connected app (bfo_…), sent asAuthorization: Bearer …. Each action needs one scope: its area scope (e.g.brews:write) or the umbrella scoperead/write.
Discover the actions
GET /api/v1/actions lists every action with its title, description, toolset, access, required scope and the JSON Schema of its input and output. It needs no token. Narrow it with ?toolsets=brewing,cellar and ?read_only=1:
curl "https://brewforge.sh/api/v1/actions?toolsets=brewing&read_only=1"{
"toolsets": [{ "name": "core", "title": "Getting started", "description": "…" }, …],
"actions": [
{
"name": "get_started",
"title": "Get started",
"toolset": "core",
"access": "read",
"required_scope": null,
"endpoint": "/api/v1/actions/get_started",
"input_schema": { … },
"output_schema": { … }
},
…
]
}access is read, write or destructive. The same information is in the OpenAPI document, where every action is an operation tagged Actions: <toolset>.
Call an action
Send the input as JSON body to POST /api/v1/actions/{name}. The response body is the result. Start with get_started: it tells you the account, plan, display units, enabled features and what the token may do.
curl -X POST https://brewforge.sh/api/v1/actions/get_started \
-H "Authorization: Bearer bfk_your_token_here"{
"account": { "name": "Agent Test User", "username": "agent-test-user", "plan": "Pro" },
"display_units": { "volume": "liters", "weight": "kg", "temperature": "celsius", "gravity": "plato", "color": "ebc", "currency": "EUR", "note": "…" },
"features": { "enabled": [ … ], "not_enabled": [ … ] },
"access": { "scopes": ["read", "write"], "can_write": true },
"brews": { "total": 34, "by_status": { "fermenting": 3, "planned": 5, … } },
"toolsets": [ … ],
"conventions": [ … ]
}An empty body counts as {}. Unknown fields are rejected, so typos don't go unnoticed.
Conventions
References by id or name
Any parameter that points at something (brew, recipe, ingredient, profile, vessel, tap list, style, …) takes its id or its exact name. Brews also take their batch number (12 or "#12"). Case doesn't matter.
When a name matches nothing or several things, the error lists candidates with their ids, so you can retry without a separate search:
curl -X POST https://brewforge.sh/api/v1/actions/get_brew \
-H "Authorization: Bearer bfk_your_token_here" \
-d '{"brew": "pale"}'{
"error": {
"code": "NOT_FOUND",
"message": "Brew \"pale\" not found.",
"hint": "Similar names are listed in candidates; call again with one of their ids.",
"candidates": [
{ "id": "f3a624c7-…", "name": "Citra Pale Ale", "batch_number": 12, "status": "fermenting", "date": "2026-11-08" },
{ "id": "83a260d6-…", "name": "WP3 Pale Ale", "batch_number": 18, "status": "fermenting" }
]
}
}Units
Values are in canonical units, and the unit is part of the field name: gravity as SG (og_sg), temperatures in °C (temp_c), volumes in litres (volume_l), weights in grams or kilograms (amount_g, grain_total_kg), percentages (abv_pct), color in EBC (color_ebc).
Where brewers measure in other units, the input has a plain field plus a unit field: gravity with gravity_unit ("sg" or "plato"), temp with temp_unit ("c" or "f"). Without the unit field the canonical unit applies; your display preferences in the app are never applied silently. Implausible values are rejected with a hint (a "gravity" of 12 looks like °Plato). Results are always canonical, as in the example at the top: 3.1 °P came back as gravity_sg: 1.012.
Lists, cursors and include
Lists return compact rows (id, name and the few fields that identify a thing) plus next_cursor. Pass it as cursor to get the next page; null means there is no more. limit sets the page size.
curl -X POST https://brewforge.sh/api/v1/actions/find_brews \
-H "Authorization: Bearer bfk_your_token_here" \
-d '{"limit": 3}'{
"items": [
{ "id": "f3a624c7-…", "name": "Citra Pale Ale", "batch_number": 12, "status": "fermenting", "style": "American Pale Ale", "brew_date": "2026-11-08", "tags": ["hoppy", "session"], "pinned": true },
{ "id": "fe6a99e4-…", "name": "Tettnanger Pils", "batch_number": 9, "status": "conditioning", "style": "German Pils", "brew_date": "2026-10-03", "tags": ["lager", "german", "hoppy"] },
{ "id": "55546f71-…", "name": "WP3 Saison S", "batch_number": 29, "status": "completed" }
],
"next_cursor": "eyJvIjozfQ"
}Detail actions return a summary and take include for heavy sections, e.g. get_brew with "include": ["recipe", "readings"]. Fields without a value are left out instead of being null.
Deleting needs confirm
Actions marked destructive (deleting a brew, a profile, readings, undoing an import, …) change nothing unless the input has "confirm": true. Without it they return a preview:
curl -X POST https://brewforge.sh/api/v1/actions/delete_brew \
-H "Authorization: Bearer bfk_your_token_here" \
-d '{"brew": "#12"}'{
"needs_confirmation": true,
"would_delete": {
"brew": { "id": "f3a624c7-…", "name": "Citra Pale Ale", "batch_number": 12, "status": "fermenting", "date": "2026-11-08" },
"fermentation_readings": 24,
"notes": 1
},
"message": "Nothing was changed. Call delete_brew again with the same input and confirm: true to do it."
}The preview runs the same checks as the real call, so a delete that would be refused (say, beer is still left in a keg) already fails here with the reason.
Export links
Exports that are files return a short-lived link instead of the file. export_brew with "format": "recipe_pdf" (or brewday_pdf, fermentation_pdf) answers with a download_url and expires_at. The link works without a token for 15 minutes and only for that one brew and sheet. Text formats (beerxml, json) come back inline as content with a filename. Tap list menu PDFs (get_taplist, manage_taplist_sharing) use the same kind of link.
{
"brew": { "id": "f3a624c7-…", "name": "Citra Pale Ale" },
"format": "recipe_pdf",
"download_url": "https://brewforge.sh/api/v1/exports/…",
"expires_at": "2026-11-11T15:45:44.225Z"
}Errors
Every failure has the same shape, on the actions API and in MCP tool results:
{
"error": {
"code": "SCOPE_REQUIRED",
"message": "This token may not call log_fermentation_reading: it needs the scope \"brews:write\" or \"write\".",
"hint": "Edit the token's access in BrewForge under Settings → API, or use a token with more scopes.",
"details": { "required_scope": "brews:write" }
}
}message says what happened and what to do next. Optional fields: hint, candidates (things to retry with), fields (field path → messages, for invalid input) and details (machine-readable extras such as required_plan or retry_after_s).
| Code | HTTP | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Missing, unknown, expired or revoked token. The response has a WWW-Authenticate header for OAuth discovery. |
TIER_REQUIRED | 403 | The plan doesn't include the API or the plan feature the action needs (details.required_plan) |
SCOPE_REQUIRED | 403 | The token lacks the scope (details.required_scope) |
FORBIDDEN | 403 | Not allowed: a feature turned off for the account, or a tool not enabled on this MCP connection |
LIMIT_REACHED | 403 | A plan limit, e.g. the number of brews |
NOT_FOUND | 404 | The referenced thing doesn't exist; candidates lists similar ones |
UNKNOWN_ACTION | 404 | No action with this name; the hint suggests similar names |
AMBIGUOUS_REFERENCE | 409 | The name matches several things; candidates lists them |
CONFLICT | 409 | The action can't run in the current state; the message says what to do first |
VALIDATION_ERROR | 400 | Invalid input; fields names each problem |
RATE_LIMITED | 429 | Too many requests; details.retry_after_s and the Retry-After header say how long to wait |
INTERNAL_ERROR | 500 | Something went wrong on our side |
Scopes and limits
- Scopes: each action belongs to an area (
brews,cellar,inventory,equipment,styles,profiles,custom-fields,settings,community) and needs<area>:readto read or<area>:writeto change. The umbrella scopesreadandwritecover all areas.get_startedworks with any valid token. Details: Authentication. - Rate limits: the actions API and the MCP server share their own limit of 600 requests per hour and 20,000 per 30 days per account, separate from the REST API. See Rate limits.