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.
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 |
JSON Schema
{
"$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.
Call it yourself
curl for this page
curl "https://apis.io/api/v1/json-schemas/bettermenu-create-custom-ingredient-request"
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.