BrewForge Docs

Put a beer in a vessel, or change a stay

Create or change a stay (one beer in one cellar vessel for some days). Create: pass vessel and brew (or beer_name for a keg of beer that is not one of the brewer's brews), plus start_date (default today) and optionally end_date. A start_date in the future plans the stay. Change: pass stay (id, vessel name or brew) and only the fields to change; vessel moves it to another vessel. If new dates overlap later stays, nothing changes and the result has clash with would_push: show it to the user and call again with push: true to move those stays later. To fill kegs/bottles from a tank use package_beer; to empty a vessel today use end_stay. Volumes in litres; dates YYYY-MM-DD, end_date exclusive. Needs the plan feature `cellar`. Scope: `cellar:write` (or `write`).

POST
/api/v1/actions/save_stay

Create or change a stay (one beer in one cellar vessel for some days). Create: pass vessel and brew (or beer_name for a keg of beer that is not one of the brewer's brews), plus start_date (default today) and optionally end_date. A start_date in the future plans the stay. Change: pass stay (id, vessel name or brew) and only the fields to change; vessel moves it to another vessel. If new dates overlap later stays, nothing changes and the result has clash with would_push: show it to the user and call again with push: true to move those stays later. To fill kegs/bottles from a tank use package_beer; to empty a vessel today use end_stay. Volumes in litres; dates YYYY-MM-DD, end_date exclusive.

Needs the plan feature cellar. Scope: cellar:write (or write).

AuthorizationBearer <token>

API token in format: bfk_. Each operation lists the token scope it requires (the scopes are listed below).

  • read: Read everything (all areas)
  • write: Create, change and delete everything (all areas)
  • brews:read: List and view brews
  • brews:write: Create, update, delete brews and notes
  • inventory:read: List inventory items
  • inventory:write: Create, update, delete inventory items
  • equipment:read: List equipment profiles
  • equipment:write: Create, update, delete equipment profiles
  • styles:read: List style profiles
  • styles:write: Create, update, delete style profiles
  • profiles:read: List mash, fermentation, and water profiles
  • custom-fields:read: List custom field definitions
  • custom-fields:write: Create, update, delete custom field definitions
  • profiles:write: Create, update, delete mash, fermentation, and water profiles
  • cellar:read: View cellar, packaged stock, tap lists, and labels
  • cellar:write: Manage cellar, packaging, stock, tap lists, and labels
  • settings:read: View preferences, imports, calculators, and your data export
  • settings:write: Change preferences and undo imports
  • community:read: View community, feedback, tickets, inbox, and account overview
  • community:write: Post, vote, and reply in community, feedback, and tickets

In: header

Scope: cellar:write

Request Body

application/json

stay?string

Change this existing stay. Omit to create a new one. The stay: its id, or the vessel it is in (e.g. "Fermenter 1": the current stay there, else its only upcoming one), or the brew in it (id, batch number or exact name). Ids come from get_cellar.

vessel?string

Vessel id or exact name, e.g. "Fermenter 1". Required to create; when changing, moves the stay there.

brew?string

Create only: the beer that goes in. The brew: its id, its batch number (e.g. 12 or "#12") or its exact name (e.g. "Citra Pale Ale"). Case does not matter.

beer_name?string

Create only, instead of brew: a beer that is not one of the brewer's brews (serving kegs only), e.g. "Guest Pils".

Lengthlength <= 100
role?string

fermenting, conditioning or serving. Default: the vessel's only role, else fermenting (serving for beer_name).

Value in"fermenting" | "conditioning" | "serving"
start_date?string

First day in the vessel, YYYY-MM-DD, e.g. "2026-11-12". Create default: today.

Match^\d{4}-\d{2}-\d{2}$
end_date?|

Day the vessel is free again (exclusive), YYYY-MM-DD; null = no end, until end_stay.

volume_l?|

Litres in the vessel, e.g. 21.5. null = unknown.

name?|

Optional label of the stay, e.g. "Dry hop" (default: the role).

notes?|

Free notes.

push?boolean

Changing dates only: true moves the following stays later when the new dates overlap them (see clash.would_push of the previous call).

today?string

The brewer's local date today, YYYY-MM-DD (e.g. "2026-11-11"). Optional: defaults to today in UTC. Pass it when the brewer's day differs from UTC (late evening in America, early morning in Asia).

Match^\d{4}-\d{2}-\d{2}$
[key: string]?never

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://brewforge.sh/api/v1/actions/save_stay" \  -H "Content-Type: application/json" \  -d '{}'
{
  "saved": true,
  "stay": {
    "id": "string",
    "vessel": "string",
    "vessel_id": "string",
    "beer": "string",
    "brew_id": "string",
    "role": "string",
    "name": "string",
    "start_date": "string",
    "end_date": "string",
    "volume_l": 0,
    "status": "planned",
    "notes": "string"
  },
  "pushed": [
    {
      "stay_id": "string",
      "beer": "string",
      "vessel": "string",
      "by_days": 0,
      "new_start_date": "string",
      "new_end_date": "string"
    }
  ],
  "clash": {
    "message": "string",
    "overlaps": [
      "string"
    ],
    "would_push": [
      {
        "stay_id": "string",
        "beer": "string",
        "vessel": "string",
        "by_days": 0,
        "new_start_date": "string",
        "new_end_date": "string"
      }
    ],
    "blocker": "string"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "hint": "string",
    "candidates": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    },
    "details": {}
  }
}