BrewForge Docs

Actions-API

Die Actions-API von BrewForge: aufgabenbezogene Actions wie log_fermentation_reading oder package_beer per HTTP, mit Übersicht, Verweisen per Name, kanonischen Einheiten, Bestätigung beim Löschen und Fehlern, die erklären, was zu tun ist.

Die Actions-API bietet einen HTTP-Endpunkt pro Sache, die du beim Brauen erledigst: Sude finden, eine Gärmessung eintragen, ein Bier abfüllen, die Taplist pflegen, herausfinden, was dir fehlt. Jede Action ist ein POST mit einem kleinen JSON-Body:

curl -X POST https://brewforge.sh/api/v1/actions/log_fermentation_reading \
  -H "Authorization: Bearer bfk_dein_token" \
  -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
}

Dieselben Actions sind die Tools des MCP-Servers, mit denselben Namen, Parametern und Ergebnissen. Die Tool-Referenz listet jede Action.

Actions oder REST?

BrewForge hat zwei APIs nebeneinander, mit denselben Token:

REST-API (/api/v1/brews, /api/v1/inventory, …)Actions-API (/api/v1/actions/…)
AufbauRessourcen: Datensätze auflisten, abrufen, anlegen, ändern, löschenAufgaben: eine Action pro Sache, die du in der App erledigst
UmfangSude, Notizen, Messungen, Bestand, Profile, eigene FelderAlles in der App außer Kontosicherheit, Zahlungen und Admin
VerweiseIDsIDs oder Namen ("Citra Pale Ale", Sud "#12")
ErgebnisseVollständige DatensätzeKompakte Zeilen; große Abschnitte auf Anfrage
Gut fürDatensätze mit einem anderen System abgleichenSkripte, Automationen und KI-Agenten, die wie ein Brauer handeln
Limit100 pro Stunde, 1.000 pro 30 Tage600 pro Stunde, 20.000 pro 30 Tage

Die REST-API bleibt, wie sie ist (Überblick). Nimm die Actions-API für alles, was die REST-API nicht abdeckt, oder wenn du sonst mehrere REST-Aufrufe hintereinander bräuchtest.

Voraussetzungen

  • Mindestens der Pro-Tarif. Andere Tarife bekommen TIER_REQUIRED. Manche Actions brauchen zusätzlich eine Tariffunktion (Keller, Taplisten, Etiketten, …); die Tool-Referenz nennt sie.
  • Ein Token: ein API-Token (bfk_…) oder das OAuth-Zugriffstoken einer verbundenen App (bfo_…), gesendet als Authorization: Bearer …. Jede Action braucht eine Berechtigung: ihre Bereichs-Berechtigung (z. B. brews:write) oder die Sammel-Berechtigung read / write.

Actions entdecken

GET /api/v1/actions listet jede Action mit Titel, Beschreibung, Toolset, Zugriff, nötiger Berechtigung und dem JSON-Schema von Ein- und Ausgabe. Dafür brauchst du kein Token. Mit ?toolsets=brewing,cellar und ?read_only=1 grenzt du die Liste ein:

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 ist read, write oder destructive. Dieselben Angaben stehen im OpenAPI-Dokument, in dem jede Action eine Operation mit dem Tag Actions: <Toolset> ist.

Eine Action aufrufen

Schick die Eingabe als JSON-Body an POST /api/v1/actions/{name}. Der Antwort-Body ist das Ergebnis. Fang mit get_started an: Die Action nennt Konto, Tarif, Anzeigeeinheiten, freigeschaltete Funktionen und was das Token darf.

curl -X POST https://brewforge.sh/api/v1/actions/get_started \
  -H "Authorization: Bearer bfk_dein_token"
{
  "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": [ … ]
}

Ein leerer Body zählt als {}. Unbekannte Felder werden abgelehnt, damit Tippfehler nicht untergehen.

Konventionen

Verweise per ID oder Name

Jeder Parameter, der auf etwas zeigt (Sud, Rezept, Zutat, Profil, Behälter, Taplist, Bierstil, …), nimmt dessen ID oder den genauen Namen. Sude nehmen auch ihre Sudnummer (12 oder "#12"). Groß- und Kleinschreibung spielt keine Rolle.

Passt ein Name zu nichts oder zu mehreren Dingen, listet der Fehler Kandidaten mit ihren IDs, damit du es ohne eigene Suche noch einmal versuchen kannst:

curl -X POST https://brewforge.sh/api/v1/actions/get_brew \
  -H "Authorization: Bearer bfk_dein_token" \
  -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" }
    ]
  }
}

Einheiten

Werte haben kanonische Einheiten, und die Einheit steht im Feldnamen: Extrakt als SG (og_sg), Temperaturen in °C (temp_c), Volumen in Litern (volume_l), Gewichte in Gramm oder Kilogramm (amount_g, grain_total_kg), Prozent (abv_pct), Farbe in EBC (color_ebc).

Wo Brauer in anderen Einheiten messen, hat die Eingabe ein einfaches Feld plus ein Einheitenfeld: gravity mit gravity_unit ("sg" oder "plato"), temp mit temp_unit ("c" oder "f"). Ohne Einheitenfeld gilt die kanonische Einheit; deine Anzeigeeinstellungen aus der App werden nie stillschweigend angewendet. Unplausible Werte werden mit einem Hinweis abgelehnt (ein „gravity“ von 12 sieht nach °Plato aus). Ergebnisse sind immer kanonisch, wie im Beispiel oben: Aus 3,1 °P wurde gravity_sg: 1.012.

Listen, Cursor und include

Listen liefern kompakte Zeilen (ID, Name und die wenigen Felder, an denen man etwas erkennt) plus next_cursor. Gib ihn als cursor mit, um die nächste Seite zu bekommen; null heißt, es gibt nichts mehr. limit legt die Seitengröße fest.

curl -X POST https://brewforge.sh/api/v1/actions/find_brews \
  -H "Authorization: Bearer bfk_dein_token" \
  -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 liefern eine Zusammenfassung und nehmen include für große Abschnitte, z. B. get_brew mit "include": ["recipe", "readings"]. Felder ohne Wert fehlen, statt null zu sein.

Löschen braucht confirm

Als destructive markierte Actions (einen Sud, ein Profil oder Messungen löschen, einen Import rückgängig machen, …) ändern nichts, solange die Eingabe kein "confirm": true enthält. Ohne liefern sie eine Vorschau:

curl -X POST https://brewforge.sh/api/v1/actions/delete_brew \
  -H "Authorization: Bearer bfk_dein_token" \
  -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."
}

Die Vorschau macht dieselben Prüfungen wie der echte Aufruf: Ein Löschen, das abgelehnt würde (etwa weil noch Bier im Fass ist), scheitert schon hier mit dem Grund.

Exporte, die Dateien sind, liefern einen kurzlebigen Link statt der Datei. export_brew mit "format": "recipe_pdf" (oder brewday_pdf, fermentation_pdf) antwortet mit download_url und expires_at. Der Link funktioniert 15 Minuten lang ohne Token und nur für diesen einen Sud und dieses Blatt. Textformate (beerxml, json) kommen direkt als content mit filename zurück. Getränkekarten-PDFs von Taplisten (get_taplist, manage_taplist_sharing) nutzen dieselbe Art 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"
}

Fehler

Jeder Fehler hat dieselbe Form, in der Actions-API und in MCP-Tool-Ergebnissen:

{
  "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 sagt, was passiert ist und was als Nächstes zu tun ist. Optionale Felder: hint, candidates (Kandidaten für einen neuen Versuch), fields (Feldpfad → Meldungen, bei ungültiger Eingabe) und details (maschinenlesbare Zusatzangaben wie required_plan oder retry_after_s).

CodeHTTPBedeutung
UNAUTHORIZED401Token fehlt, ist unbekannt, abgelaufen oder widerrufen. Die Antwort hat einen WWW-Authenticate-Header für die OAuth-Discovery.
TIER_REQUIRED403Der Tarif enthält die API oder die nötige Tariffunktion nicht (details.required_plan)
SCOPE_REQUIRED403Dem Token fehlt die Berechtigung (details.required_scope)
FORBIDDEN403Nicht erlaubt: eine für das Konto abgeschaltete Funktion oder ein Tool, das auf dieser MCP-Verbindung nicht aktiv ist
LIMIT_REACHED403Ein Tariflimit, z. B. die Zahl der Sude
NOT_FOUND404Das Referenzierte gibt es nicht; candidates listet Ähnliches
UNKNOWN_ACTION404Keine Action mit diesem Namen; der Hinweis schlägt ähnliche vor
AMBIGUOUS_REFERENCE409Der Name passt zu mehreren Dingen; candidates listet sie
CONFLICT409Die Action geht im aktuellen Zustand nicht; die Meldung sagt, was zuerst zu tun ist
VALIDATION_ERROR400Ungültige Eingabe; fields nennt jedes Problem
RATE_LIMITED429Zu viele Anfragen; details.retry_after_s und der Header Retry-After sagen, wie lange du warten sollst
INTERNAL_ERROR500Bei uns ist etwas schiefgegangen

Berechtigungen und Limits

  • Berechtigungen: Jede Action gehört zu einem Bereich (brews, cellar, inventory, equipment, styles, profiles, custom-fields, settings, community) und braucht <bereich>:read zum Lesen oder <bereich>:write zum Ändern. Die Sammel-Berechtigungen read und write decken alle Bereiche ab. get_started geht mit jedem gültigen Token. Details: Authentifizierung.
  • Rate-Limits: Actions-API und MCP-Server teilen sich ein eigenes Limit von 600 Anfragen pro Stunde und 20.000 pro 30 Tage pro Konto, getrennt von der REST-API. Siehe Rate-Limits.

Weiter

Auf dieser Seite