BrewForge Docs

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/…)
ShapeResources: list, get, create, update, delete recordsTasks: one action per thing you do in the app
CoversBrews, notes, readings, inventory, profiles, custom fieldsEverything in the app except account security, payments and admin
ReferencesIdsIds or names ("Citra Pale Ale", batch "#12")
ResultsFull recordsCompact rows; heavy sections on request
Best forSyncing records with another systemScripts, automations and AI agents that act like a brewer
Limit100 per hour, 1,000 per 30 days600 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 as Authorization: Bearer …. Each action needs one scope: its area scope (e.g. brews:write) or the umbrella scope read / 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.

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).

CodeHTTPMeaning
UNAUTHORIZED401Missing, unknown, expired or revoked token. The response has a WWW-Authenticate header for OAuth discovery.
TIER_REQUIRED403The plan doesn't include the API or the plan feature the action needs (details.required_plan)
SCOPE_REQUIRED403The token lacks the scope (details.required_scope)
FORBIDDEN403Not allowed: a feature turned off for the account, or a tool not enabled on this MCP connection
LIMIT_REACHED403A plan limit, e.g. the number of brews
NOT_FOUND404The referenced thing doesn't exist; candidates lists similar ones
UNKNOWN_ACTION404No action with this name; the hint suggests similar names
AMBIGUOUS_REFERENCE409The name matches several things; candidates lists them
CONFLICT409The action can't run in the current state; the message says what to do first
VALIDATION_ERROR400Invalid input; fields names each problem
RATE_LIMITED429Too many requests; details.retry_after_s and the Retry-After header say how long to wait
INTERNAL_ERROR500Something 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>:read to read or <area>:write to change. The umbrella scopes read and write cover all areas. get_started works 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.

Next steps

On this page