BrewForge Docs

Create, change or archive a custom field

Create a custom field definition (omit field) or change one (field = its key, name or id). Brew fields (scope "brew", default) need a placement: the brew page section they appear in. Brew note fields (scope "brew_note") have no placement. Type and scope are fixed after creation. archived: true hides a field in the app (values stay), false restores it; delete it for good with delete_custom_field. Example: {"name": "Mash pH", "type": "number", "placement": "brew_day", "unit": "pH"}. Values on brews are set with the brewing tools. Scope: `custom-fields:write` (or `write`).

POST
/api/v1/actions/save_custom_field

Create a custom field definition (omit field) or change one (field = its key, name or id). Brew fields (scope "brew", default) need a placement: the brew page section they appear in. Brew note fields (scope "brew_note") have no placement. Type and scope are fixed after creation. archived: true hides a field in the app (values stay), false restores it; delete it for good with delete_custom_field. Example: {"name": "Mash pH", "type": "number", "placement": "brew_day", "unit": "pH"}. Values on brews are set with the brewing tools.

Scope: custom-fields: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: custom-fields:write

Request Body

application/json

field?string

Change this field. The custom field: its id, key (e.g. "mash-ph") or exact name (e.g. "Mash pH"). Case does not matter. list_custom_fields shows them. Omit to create a new one.

name?string

Label shown in the app. Required when creating. Example: "Mash pH".

Length1 <= length <= 50
key?string

New fields only: stable key (lowercase, digits, dashes), e.g. "mash-ph". Default: made from the name.

type?string

New fields only: "text", "number", "integer", "date", "time", "datetime", "boolean", "select" or "url". Default "text".

Value in"text" | "number" | "integer" | "date" | "time" | "datetime" | "boolean" | "select" | "url"
scope?string

New fields only: "brew" (a value per brew, default) or "brew_note" (a value per brew note).

Value in"brew" | "brew_note"
placement?string

Brew fields: page section, "brew_details", "brew_day", "fermentation", "packaging" or "tasting". Required for new brew fields.

Value in"brew_details" | "brew_day" | "fermentation" | "packaging" | "tasting"
choices?array<>

Select fields: the options, 2-20. Example: ["clear", "hazy", "murky"].

Items2 <= items <= 20
unit?|

Unit label for number fields, e.g. "pH" or "g/L"; null clears it.

placeholder?|

Hint text shown in the empty input; null clears it.

default_value?|||

Pre-filled value for new brews, matching the type (e.g. 5.4, true, "clear"); null clears it.

description?|

Help text; null clears it.

required?boolean

true: the app asks for a value.

display_order?integer

Position within its section, 0 first.

Range0 <= value
archived?boolean

Existing fields: true archives (hides) it, false restores it.

[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_custom_field" \  -H "Content-Type: application/json" \  -d '{}'
{
  "saved": "created",
  "field": {
    "id": "string",
    "key": "string",
    "name": "string",
    "type": "string",
    "scope": "string",
    "placement": "string",
    "choices": [
      "string"
    ],
    "unit": "string",
    "placeholder": "string",
    "default_value": "string",
    "description": "string",
    "required": true,
    "display_order": 0,
    "archived": true,
    "archived_at": "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": {}
  }
}