BetterMenu · Schema

CreateCustomIngredientRequest

Create a custom ingredient, optionally with nutrients and serving in one shot. Only `name` is required. `nutrients` and the serving fields (`reference_amount`, `reference_unit`, `household_measure`, `reference_quantity_g`, `density_g_per_ml`) are optional and order-agnostic — when supplied, the first committed Version already carries them (one draft version), instead of requiring a create-then-two-PUTs sequence. Omitted fields keep the entity's empty default, exactly as a name-only create. The created entity always starts in `draft` status — confirming (draft -> active) remains a separate, deliberate step.

Food TechRecipeFormulationFDA ComplianceSoftware-as-a-ServiceCloud

Properties

Name Type Description
name string User-given custom ingredient name.
approved_markets object Markets this ingredient is approved for. Omitted (`None`) defaults to the org's market, so the ingredient is searchable/gettable immediately.
nutrients object The complete nutrient list. Omitted (`None`) leaves the entity's empty draft nutrient list untouched.
reference_amount object Serving as entered, e.g. 15 / 100 / 1.
reference_unit object Unit the reference amount is expressed in — metric (g, ml), household (tablespoon, cup), or a count (e.g. 'cookie', 'slice').
household_measure object Display/source provenance, e.g. "1 Tablespoon".
reference_quantity_g object Derived as-sold gram basis.
density_g_per_ml object
View JSON Schema on GitHub

JSON Schema

bettermenu-create-custom-ingredient-request-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bettermenu/json-schema/bettermenu-create-custom-ingredient-request-schema.json",
  "title": "CreateCustomIngredientRequest",
  "description": "Create a custom ingredient, optionally with nutrients and serving in one shot.\n\nOnly `name` is required. `nutrients` and the serving fields\n(`reference_amount`, `reference_unit`, `household_measure`,\n`reference_quantity_g`, `density_g_per_ml`) are optional and\norder-agnostic — when supplied, the first committed Version already\ncarries them (one draft version), instead of requiring a\ncreate-then-two-PUTs sequence. Omitted fields keep the entity's\nempty default, exactly as a name-only create. The created entity\nalways starts in `draft` status — confirming (draft -> active)\nremains a separate, deliberate step.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bettermenu-studio-api-openapi.yml#/components/schemas/CreateCustomIngredientRequest",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "title": "Name",
      "description": "User-given custom ingredient name."
    },
    "approved_markets": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/CountryCode"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Approved Markets",
      "description": "Markets this ingredient is approved for. Omitted (`None`) defaults to the org's market, so the ingredient is searchable/gettable immediately."
    },
    "nutrients": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/CustomNutrient-Input"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Nutrients",
      "description": "The complete nutrient list. Omitted (`None`) leaves the entity's empty draft nutrient list untouched."
    },
    "reference_amount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reference Amount",
      "description": "Serving as entered, e.g. 15 / 100 / 1."
    },
    "reference_unit": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reference Unit",
      "description": "Unit the reference amount is expressed in — metric (g, ml), household (tablespoon, cup), or a count (e.g. 'cookie', 'slice')."
    },
    "household_measure": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Household Measure",
      "description": "Display/source provenance, e.g. \"1 Tablespoon\"."
    },
    "reference_quantity_g": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reference Quantity G",
      "description": "Derived as-sold gram basis."
    },
    "density_g_per_ml": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
        },
        {
          "type": "null"
        }
      ],
      "title": "Density G Per Ml"
    }
  },
  "type": "object",
  "required": [
    "name"
  ],
  "$defs": {
    "CountryCode": {
      "type": "string",
      "enum": [
        "US"
      ],
      "title": "CountryCode",
      "description": "Market code: the country whose food data and labelling rules apply.\n\nParameters name it `market`, `country` or `country_code`; all take this value."
    },
    "CustomNutrient-Input": {
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 26,
              "minLength": 26,
              "pattern": "^nrow_[a-z0-9]{21}$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Id",
          "description": "Stable per-row identifier (nrow_xxx) for diff/identity purposes only — not a nutrient vocabulary reference. Omit when adding a new row; the server mints one. Send back verbatim when editing an existing row so its identity is preserved across saves."
        },
        "unit": {
          "type": "string",
          "title": "Unit",
          "description": "Unit the amount is expressed in. Once the nutrient resolves to a market identity, the unit must match that nutrient's canonical unit — a mismatch is rejected."
        },
        "amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string",
              "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"
            },
            {
              "type": "null"
            }
          ],
          "title": "Amount",
          "description": "Present-with-value, present-as-zero, or unknown (None). None must never be coerced to zero."
        },
        "market_nutrients": {
          "additionalProperties": {
            "$ref": "#/$defs/MarketNutrient"
          },
          "propertyNames": {
            "$ref": "#/$defs/CountryCode"
          },
          "type": "object",
          "title": "Market Nutrients",
          "description": "Per-market nutrient identity, one entry per approved market. An entry is present once the nutrient resolves for that market; a nutrient that cannot resolve for a market has no entry there and degrades off that market's label. Empty until a market is approved."
        }
      },
      "type": "object",
      "required": [
        "unit"
      ],
      "title": "CustomNutrient",
      "description": "A user-provided nutrient value on a custom ingredient.\n\nCarries the physical value (``amount`` + ``unit``) and the nutrient's\nidentity in each approved market (``market_nutrients``). ``amount`` is\ntri-state: a value, zero, or unknown (``None``); unknown is never zero.\n``id`` identifies the row, not the nutrient: omit it on a new row and\nsend it back unchanged when editing an existing one."
    },
    "MarketNutrient": {
      "properties": {
        "bmid": {
          "type": "string",
          "pattern": "^n_[a-z0-9_]+$",
          "title": "Bmid",
          "description": "Canonical BetterMenu nutrient identity for this market — a resolved reference to an existing vocabulary entry, never minted per ingredient. A nutrient with no existing entry is a governed vocabulary-extension case, not something an ingredient mints."
        },
        "nutrient_id": {
          "type": "integer",
          "exclusiveMinimum": 0.0,
          "title": "Nutrient Id",
          "description": "The market's official regulatory nutrient id (e.g. a USDA numeric id, an FSANZ code)."
        }
      },
      "type": "object",
      "required": [
        "bmid",
        "nutrient_id"
      ],
      "title": "MarketNutrient",
      "description": "A nutrient's identity within one market's regulatory system: the\ncanonical ``bmid`` paired with that market's official nutrient id.\n\nThe whole pair is per-market because both halves can diverge across\nmarkets. Most nutrients share one ``bmid`` (Protein is the same bmid in\nthe US and FSANZ; only the regulatory id differs), but\nmethodology-divergent ones do not — US energy in kcal and FSANZ energy in\nkJ carry different bmids as well as different ids. One nutrient's identity\nas a single market's regulatory system expresses it."
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/bettermenu-create-custom-ingredient-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.