Servers Playground How we check Add a server Log in

Befana Recipes

Working · 1.6 s

app.befana/befanav0.2.0 Domain verified

Ad-free recipes with amounts in every step: search, scale, plan meals, build shopping lists.

Entertainment & Games Commerce

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://befana.app/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

build_shopping_list

Merge recipes (each at its own servings) and anything else into one shopping list by aisle, in what a store sells (10 cloves garlic → 1 head). Use for "make me a list", "what do I need to buy?" or "add paper towels and 2 lb bananas" (extra_items keep the cook's amounts). What the cook has stays off (left_off); staples and small amounts of bulk items (3 tbsp flour) come back as likely_have, not bought: ask which they have or are out of, then update_shopping_list. Items that hit their allergies are flagged privately for this cook; warnings are not saved in the shareable list. Signed in, the list is saved and returns a shareable url and an id for order_groceries; signed out it comes back unsaved (keep: true asks them to sign in).

recipesarray, required

keepboolean

Older spelling of save: true = save, false = preview. Still works; prefer save

savestring

"preview": show the list and keep nothing (no id, no url, nothing in My Kitchen), signed in or out; use it when the cook says "just show me", "don't save it yet", "an option". "save": keep it in the cook's kitchen (signed out: the sign-in error). Left out: a signed-in call saves, a signed-out call previews. The receipt in the result says which happened

unitsstring

US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.

pantryarray

Ingredients the cook already has, e.g. ["flour", "eggs"]

extra_itemsarray

Anything else for the same trip, as the cook said it, amount included: ["paper towels", "2 lb bananas"]. A matching recipe ingredient gets that quantity added when the units agree, or both amounts when they don't.

request_keystring

Your own id or receipt.request_key. First save wins for this cook and tool: within 10 minutes the same key returns the saved list, even if arguments changed. New arguments need a new key; edits use update_*. Without a key Befana fingerprints arguments and applied preferences/pantry

include_staplesboolean

Put salt, oil, sugar, etc. on the list instead of the pantry check

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Befana Recipes MCP server | mcptry

Befana Recipes

Working · 1.6 s

app.befana/befanav0.2.0 Domain verified

Ad-free recipes with amounts in every step: search, scale, plan meals, build shopping lists.

Entertainment & Games Commerce

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://befana.app/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

build_shopping_list

recipesarray, required

keepboolean

Older spelling of save: true = save, false = preview. Still works; prefer save

savestring

unitsstring

US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.

pantryarray

Ingredients the cook already has, e.g. ["flour", "eggs"]

extra_itemsarray

request_keystring

include_staplesboolean

Put salt, oil, sugar, etc. on the list instead of the pantry check

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Tools (25)

build_shopping_list

Argument	Type	Description
keep	boolean	Older spelling of save: true = save, false = preview. Still works; prefer save
save	string	"preview": show the list and keep nothing (no id, no url, nothing in My Kitchen), signed in or out; use it when the cook says "just show me", "don't save it yet", "an option". "save": keep it in the cook's kitchen (signed out: the sign-in error). Left out: a signed-in call saves, a signed-out call previews. The receipt in the result says which happened
units	string	US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.
pantry	array	Ingredients the cook already has, e.g. ["flour", "eggs"]
recipes*	array
extra_items	array	Anything else for the same trip, as the cook said it, amount included: ["paper towels", "2 lb bananas"]. A matching recipe ingredient gets that quantity added when the units agree, or both amounts when they don't.
request_key	string	Your own id or receipt.request_key. First save wins for this cook and tool: within 10 minutes the same key returns the saved list, even if arguments changed. New arguments need a new key; edits use update_*. Without a key Befana fingerprints arguments and applied preferences/pantry
include_staples	boolean	Put salt, oil, sugar, etc. on the list instead of the pantry check

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "recipes"
  ],
  "properties": {
    "keep": {
      "type": "boolean",
      "description": "Older spelling of save: true = save, false = preview. Still works; prefer save"
    },
    "save": {
      "enum": [
        "save",
        "preview"
      ],
      "type": "string",
      "description": "\"preview\": show the list and keep nothing (no id, no url, nothing in My Kitchen), signed in or out; use it when the cook says \"just show me\", \"don't save it yet\", \"an option\". \"save\": keep it in the cook's kitchen (signed out: the sign-in error). Left out: a signed-in call saves, a signed-out call previews. The receipt in the result says which happened"
    },
    "units": {
      "enum": [
        "us",
        "metric"
      ],
      "type": "string",
      "description": "US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting."
    },
    "pantry": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ingredients the cook already has, e.g. [\"flour\", \"eggs\"]"
    },
    "recipes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "slug"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "servings": {
            "type": "number",
            "maximum": 1000,
            "minimum": 0.25
          }
        }
      },
      "maxItems": 21,
      "minItems": 1
    },
    "extra_items": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 50,
      "description": "Anything else for the same trip, as the cook said it, amount included: [\"paper towels\", \"2 lb bananas\"]. A matching recipe ingredient gets that quantity added when the units agree, or both amounts when they don't."
    },
    "request_key": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "Your own id or receipt.request_key. First save wins for this cook and tool: within 10 minutes the same key returns the saved list, even if arguments changed. New arguments need a new key; edits use update_*. Without a key Befana fingerprints arguments and applied preferences/pantry"
    },
    "include_staples": {
      "type": "boolean",
      "default": false,
      "description": "Put salt, oil, sugar, etc. on the list instead of the pantry check"
    }
  }
}

cook_profile

Read a cook's public Befana page, or change the signed-in cook's own. Use when the cook asks "who shared this?", "show me more from this cook", "what's on my profile?", or wants their name, about me, links or handle changed. Pass handle (any recipe's shared_by.handle) to read that page; nothing to read their own (signed in). To change their own, pass update with only the fields to change, after telling them exactly what will change and getting a yes (cook_confirmed). Never write about-me text for them. Returns name, about, links and public recipes with urls; ai_chef true means an AI chef persona. Nothing private is ever on a profile.

Argument	Type	Description
handle	string	Whose page to read, e.g. "andrew_rexroad" (with or without @). Omit for the signed-in cook's own
update	object	Changes to the signed-in cook's own profile; interests and links replace the saved lists. A changed handle redirects for 90 days. photo: "google" copies the account photo, null removes it
cook_confirmed	boolean	Required with update: true only after the cook said yes to this exact change

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "handle": {
      "type": "string",
      "maxLength": 40,
      "description": "Whose page to read, e.g. \"andrew_rexroad\" (with or without @). Omit for the signed-in cook's own"
    },
    "update": {
      "type": "object",
      "properties": {
        "about": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 300
            },
            {
              "type": "null"
            }
          ],
          "description": "Up to 300 characters, in the cook's words; null clears it"
        },
        "links": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "kind",
              "url"
            ],
            "properties": {
              "url": {
                "type": "string",
                "maxLength": 300
              },
              "kind": {
                "enum": [
                  "website",
                  "instagram",
                  "tiktok",
                  "youtube",
                  "substack"
                ],
                "type": "string"
              }
            }
          },
          "maxItems": 3,
          "description": "Up to 3; an Instagram, TikTok, YouTube or Substack link must be on that site; replaces the list"
        },
        "photo": {
          "anyOf": [
            {
              "type": "string",
              "const": "google"
            },
            {
              "type": "null"
            }
          ],
          "description": "\"google\" copies the account's Google photo (processed and stored by Befana); null removes the photo"
        },
        "handle": {
          "type": "string",
          "maxLength": 40,
          "description": "3 to 30 letters, digits or underscores; reserved words are refused"
        },
        "location": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ],
          "description": "As the cook says it, e.g. \"Denver\"; null clears it"
        },
        "interests": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 30
          },
          "maxItems": 10,
          "description": "Cooking interests, up to 10; replaces the list"
        },
        "display_name": {
          "type": "string",
          "maxLength": 60
        },
        "show_details": {
          "type": "boolean",
          "description": "True shows the photo, about me, location, interests and links on the public page"
        }
      },
      "description": "Changes to the signed-in cook's own profile; interests and links replace the saved lists. A changed handle redirects for 90 days. photo: \"google\" copies the account photo, null removes it"
    },
    "cook_confirmed": {
      "type": "boolean",
      "const": true,
      "description": "Required with update: true only after the cook said yes to this exact change"
    }
  }
}

create_recipe

Publish a recipe to Befana. Use with draft_id from draft_recipe once the cook has seen and confirmed the draft, passing only the fields they changed; never publish pasted text straight from fields. Pass fields without a draft only for a recipe you worked out with the cook in this conversation, after showing it to them. Steps use ingredient tags, never typed amounts: "Whisk {flour} with {salt}". Recipes are public and appear under My recipes unless visibility is "private" (just for the cook); an exact copy of one the cook already has is refused (use update_recipe). tested marks it cooked and timed only when the cook says they made it; ask, never assume. Returns the url and any warnings.

Argument	Type	Description
tags	array
steps	array
title	string
author	string	Name to credit (the cook)
tested	any	Mark the recipe tested: the cook says they cooked it themselves and timed it. Ask the cook ("Have you cooked this? About how long did it take, start to finish?") and pass only what they say; never assume it, never estimate the minutes, and never mark a recipe tested because you drafted, imported or adapted it. null clears the mark. Shown as "Tested by the cook · 45 min" and counted as one timed cook.
summary	string	One or two sentences on what makes it good
draft_id	string

delete_recipe

Delete a recipe the cook owns, for good, when nobody else has touched it (no versions, reviews or saves by other cooks). Use when the cook says "delete that test recipe", "get rid of it". Without confirm it only reports what would go and whether it can; name the recipe, get a yes, then call with confirm: true. A recipe others have cooked or saved can't be deleted: the answer points at update_recipe({ unpublished: true }), which takes it off Befana for everyone but the cook and can be undone.

destructive

Argument	Type	Description
slug*	string	The cook's own recipe
confirm	boolean	true only after the cook said yes to deleting this recipe by name

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "description": "The cook's own recipe"
    },
    "confirm": {
      "type": "boolean",
      "default": false,
      "description": "true only after the cook said yes to deleting this recipe by name"
    }
  }
}

draft_recipe

Turn a recipe the cook pasted, typed or linked into a draft to check: ingredients matched, steps in plain words with the amounts as tags, servings, times and timers filled in. Nothing is published. Use when the cook says "save my grandma's meatballs", "add this one" with a link, or shows you a recipe card (read it yourself and pass the text). Show the draft, point out the guessed fields, then publish with create_recipe({ draft_id }) once they confirm. existing means it's already on Befana: send them there (save_recipe, fork_recipe), and add_anyway only if they say it's a different recipe. blocked means the site only opens for its readers: pass the page's text with source_url if you can see it.

Argument	Type	Description
url	string	A public recipe page (http or https), or a Pinterest Pin or pin.it link (Befana follows the Pin to the recipe it saved). Pass text or url, not both
text	string	The recipe as the cook gave it, in any format
add_anyway	boolean	Draft it even though it matched a recipe already on Befana (only when the cook says it's a different recipe)
source_url	string	With text: the web page the recipe text came from, to credit it and to find it if it's already on Befana

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2000,
      "description": "A public recipe page (http or https), or a Pinterest Pin or pin.it link (Befana follows the Pin to the recipe it saved). Pass text or url, not both"
    },
    "text": {
      "type": "string",
      "maxLength": 20000,
      "description": "The recipe as the cook gave it, in any format"
    },
    "add_anyway": {
      "type": "boolean",
      "description": "Draft it even though it matched a recipe already on Befana (only when the cook says it's a different recipe)"
    },
    "source_url": {
      "type": "string",
      "maxLength": 2000,
      "description": "With text: the web page the recipe text came from, to credit it and to find it if it's already on Befana"
    }
  }
}

fork_recipe

Save the cook's own version of someone else's recipe, linked to the original, which never changes. Use when the cook says "make it dairy-free and keep that", "halve the sugar", "save it for 8". Pass only what changes; ingredients or steps, if passed, are the complete new list (get_recipe first and edit it). Before calling, show the cook the changed ingredients and steps and get a yes; never save silently. It's named after the change unless you pass title. Public by default; visibility "private" keeps it just for the cook. The same change again returns their existing version (already_existed). On the cook's own recipe use update_recipe; this refuses.

Argument	Type	Description
slug*	string	The original recipe's slug
tags	array
steps	array
title	string
author	string	Name to credit (the cook)
summary	string	One or two sentences on what makes it good
servings	number
chef_note	string	The chef's note, up to 500 characters: a sentence or two in the cook's words on what makes the recipe theirs. Only what the cook said; never write one for them.

generate_placeholder_cover

Draw a labeled illustration of the dish for a recipe the cook owns that has no photo, so it looks finished until they add a real one. Use when the cook says "it needs a picture" or accepts the offer after create_recipe. Ask first; it takes up to a minute. It's drawn from the recipe's own text, labeled "Illustration, not a photo of this dish" everywhere, never counted as a photo, and never replaces a cook's photo (that's a refusal, not an error). When image generation is off, say so and point to the photo upload on the website.

Argument	Type	Description
slug*	string	The cook's own recipe

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "description": "The cook's own recipe"
    }
  }
}

get_cook_steps

A recipe as hands-free steps for cooking along: a gather list, then one step at a time with its amounts, the ingredients it uses, its tip and any timer. Use when the cook says "walk me through it", "I'm cooking it now", "what's next?" (pass step for just that one, or from_step to pick up where they left off). Give one step per reply and offer the step's timer. The recipe url shows the same steps as a checklist on their phone. Works signed out.

read-only

Argument	Type	Description
slug*	string
step	integer	Just this step (1-based), for "what's next?" in a voice flow; the gather list comes only with step 1 or no step
units	string	US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.
servings	number
allergens	array	Explicit per-request allergen screening, separate from exclude_ingredients. Use at most nine entries: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame. Fixed aliases: dairy → milk, egg → eggs, peanut → peanuts, tree nuts → tree_nuts, soya → soy, sesame seeds → sesame. Nuts and seafood are ambiguous: specify tree_nuts/peanuts or fish/shellfish explicitly. Gluten is not wheat and lactose is not milk; neither is supported here. No spelling guesses are made. Retry with supported categories. Empty adds no restriction and never clears saved rules. Not saved to Befana preferences or plans.

get_my_kitchen

What the cook keeps on Befana: saved recipes, recipes they published, their own versions, shopping lists and meal plans, their ratings, a pantry count. Use when the cook asks "what did I save?", "pull up last week's list", "show my recipes", or (section: photos) "which of my recipes need a better photo?". For an explicitly requested interrupted photo save, section pending_photos with target_recipe returns up to 30 private choices and an observed version; it neither claims recipes nor acknowledges notices. Show the chosen photo, target and replacement consequence and obtain explicit confirmation before update_recipe recover_photo. Never auto-attach or auto-confirm. Same as My Kitchen on the website. If newly_assigned is present, say its line first, once (Befana added those recipes; hand_back_recipe returns one that isn't theirs). If fixes_asked is present, pass the fixes on once and offer to make them with update_recipe after showing the changes.

read-only

Argument	Type	Description
limit	integer	Items per ordinary kitchen section; pending_photos always returns at most 30
section	string	photos: recipes needing a better cover. pending_photos: explicitly requested private recovery choices for target_recipe, at most 30 per page; neither photo section is part of all
target_recipe	string	Required only with pending_photos: the exact recipe slug whose cover the cook wants to recover
expected_actor	string	For later pending_photos pages, copy expected_actor from discovery; an account consistency check, never authorization

get_my_recipe_feedback

Read only the signed-in cook's saved private feedback and the recipe-as-written context (US units, original servings). Before new step feedback, show the referenced step and amounts, ask the cook to review them, and use this content_token with rate_recipe. Never infer stars, made-it, repeat choice or substitutions from a note. No author access to other cooks' private feedback.

read-only

Argument	Type	Description
slug*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string"
    }
  }
}

get_my_stats

How the cook's own recipes are doing: views, shares, prints, cooks, saves, versions and ratings, in total and by day, per recipe and by region. Use when a cook who publishes asks "how's my recipe doing?", "how many people cooked my dal?", "what's my most popular recipe?". Counts only, never who: the cook's own activity is left out, and a cook is someone who finished the last step, said they made it, or printed it. Lead with line, then the top recipe with its url; quote definitions.cook if asked what counts. Same numbers as /me/stats on the website.

read-only

Argument	Type	Description
range	string	The window; all is all-time totals with a year of daily rows
recipe	string	One of the cook's recipes, by slug, for just that recipe

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "range": {
      "enum": [
        "7d",
        "30d",
        "90d",
        "all"
      ],
      "type": "string",
      "default": "30d",
      "description": "The window; all is all-time totals with a year of daily rows"
    },
    "recipe": {
      "type": "string",
      "maxLength": 200,
      "description": "One of the cook's recipes, by slug, for just that recipe"
    }
  }
}

get_recipe

One recipe in full, scaled to any servings, US or metric, with every amount written into the step that uses it, so steps can be read aloud as they are. Use when the cook picks a recipe, asks "how much butter is that in tablespoons?" (pass units_for; the list and the steps follow, don't convert yourself), or wants a change ("make it dairy-free": substitute returns swaps that respect their allergies and diet; show the changed ingredients and steps, then save on their yes with fork_recipe, or update_recipe on their own). Returns the recipe, its url, step tips to pass on, and your_versions when the cook already has their own version (offer it). Mention chef_note only if asked. Works signed out.

read-only

Argument	Type	Description
slug*	string	Recipe slug from search_recipes
units	string	US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.
servings	number	Scale to this many servings (defaults to the cook's household size, then the recipe's own)
allergens	array	Explicit per-request allergen screening, separate from exclude_ingredients. Use at most nine entries: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame. Fixed aliases: dairy → milk, egg → eggs, peanut → peanuts, tree nuts → tree_nuts, soya → soy, sesame seeds → sesame. Nuts and seafood are ambiguous: specify tree_nuts/peanuts or fish/shellfish explicitly. Gluten is not wheat and lactose is not milk; neither is supported here. No spelling guesses are made. Retry with supported categories. Empty adds no restriction and never clears saved rules. Not saved to Befana preferences or plans.

hand_back_recipe

Hand back a recipe the Befana team added to the cook's kitchen (get_my_kitchen newly_assigned) when the cook says "that one isn't mine". Keeping it is the default and needs nothing. Confirm with the cook first; it works once per recipe.

destructive

Argument	Type	Description
slug*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "maxLength": 200
    }
  }
}

order_groceries

Send a shopping list to a grocer near the cook: into their cart where the store allows it (King Soopers and other Kroger stores, once connected), else one list link, else a search link per item. Use when the cook says "order these", "get it delivered", "send it to my store". No saved store: it asks their ZIP, then lists nearby grocers (choose_store); call again with store and zip, which saves it. A cart grocer first returns cart_preview: tell the cook its say (flagged items and total only), apply their changes as edits, then call with preview_id and confirm: true. Share share_url with the cook (the order is theirs: Befana's order page uses their saved store and sign-in); list_url is the link for the household. Befana never picks a brand. Keep commission_disclosure in parentheses right after the link, once.

Argument	Type	Description
zip	string	The cook's ZIP code, when they gave it; saved with their store. Never guess it
edits	array	The cook's changes to a preview ("skip the hoisin", "2 salmon"), with preview_id
store	string	The store the cook picked or named ("Sprouts", "King Soopers"), ideally one from choose_store. Saved as their store unless remember_store is false
units	string	US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.
pantry	array	Ingredients the cook already has; they are not ordered
confirm	boolean	true, with preview_id, once the cook said yes to the preview

pantry

Read or change the cook's pantry: food on hand and staples, which Befana leaves off shopping lists and uses for what-can-I-make. Use when the cook says what they have or ran out of ("I've got chicken thighs and half an onion", "we're out of eggs"), corrects it, or asks what's in it. Pass their words verbatim as text; or add/remove names; a fridge photo goes in photo (an upload name). No arguments reads it. Saying what they have is the cook's yes: save it and read the change back in one line. Never add what the cook didn't say. Returns the change (unsure lists what didn't read as food) or the whole pantry.

Argument	Type	Description
add	array	Ingredient names to add
text	string	What the cook said, verbatim
photo	string	An upload name (or its /media/ URL) from POST /api/upload with purpose "parse": a photo of the fridge or shelf to read
remove	array	Ingredient names to take out
replace	boolean	Take out every fresh item not in this update (staples stay)
staples	array	Set the always-on-hand list to exactly these

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "add": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 300,
      "description": "Ingredient names to add"
    },
    "text": {
      "type": "string",
      "maxLength": 2000,
      "description": "What the cook said, verbatim"
    },
    "photo": {
      "type": "string",
      "maxLength": 200,
      "description": "An upload name (or its /media/ URL) from POST /api/upload with purpose \"parse\": a photo of the fridge or shelf to read"
    },
    "remove": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 300,
      "description": "Ingredient names to take out"
    },
    "replace": {
      "type": "boolean",
      "default": false,
      "description": "Take out every fresh item not in this update (staples stay)"
    },
    "staples": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 100,
      "description": "Set the always-on-hand list to exactly these"
    }
  }
}

plan_meals

Plan dinners and return the finished week in one call: picks by day (varied, perishables first, one new to the cook), merged shopping list (list), prep_order, substitutions and one true line (say). Use when the cook says "what should we eat this week?", "plan dinners", "groceries for the week", "four dinners under $80" (max_budget), or has people over (occasion, guest_notes). Preferences and pantry apply. Show the plan with say and at most one next-step question; then stop and wait for the cook's next message. No second offer; nothing is ordered. A swap goes to update_meal_plan with plan_id. Signed out it comes back unsaved (keep: true asks to sign in).

Argument	Type	Description
keep	boolean	Older spelling of save: true = save, false = preview. Still works; prefer save
save	string	"preview": show the plan and keep nothing (no id, no url, nothing in My Kitchen), signed in or out; use it when the cook says "just show me", "don't save it yet", "an option". "save": keep it in the cook's kitchen (signed out: the sign-in error). Left out: a signed-in call saves, a signed-out call previews. The receipt in the result says which happened
tags	array	Required tags, e.g. ["vegetarian"]
meals	integer	How many meals to plan; leave out to use the cook's usual number (workflow.plan_meals in preferences), else 5
units	string	US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.
pantry	array

preferences

Read or change the cook's Befana preferences: allergies, diet, avoid list, household size, units, weeknight time, skill, equipment, cuisines, store, privacy, and how they want you to work, all applied to every tool. No arguments reads them. For a change the cook asks for in their own words ("switch me to metric", "set us to 4 people"), save with cook_confirmed. Allergies, diets, the avoid list, privacy, a change you suggest or a passing mention ("usually it's 4 of us") need a yes first: pass the change without cook_confirmed (nothing is saved), ask the cook confirm.say, then call again with cook_confirmed. Never infer an allergy or diet. Lists replace the saved list.

Argument	Type	Description
avoid	array	Ingredients the cook dislikes
diets	array
skill	any
store	object
units	string
pantry	array	Always-on-hand staples
servings	any	Household size; null to use each recipe's own
workflow	object	How the cook wants you to work with them. Pass only the keys that change
allergies

rate_recipe

Post the cook's star rating (1 to 5) and comment, and mark that they made it. Use when the cook says "that was great, five stars" or "I made the chili, a bit too salty". One rating per cook per recipe: calling again updates it, and a comment left out is kept. Refuses the cook's own recipe. Post only what the cook said; ask for the stars if they didn't give any. Private notes and substitutions have a 2,000-character combined limit. Optional private step feedback requires the content_token from get_my_recipe_feedback and a reviewed step context. Omitted optional answers are preserved; null or empty arrays clear only that answer. Keep stars explicit; never infer completion or preferences from notes. With made_it it finishes their cook and may offer to take what the recipe used off the pantry.

Argument	Type	Description
name	string	Display name the cook wants shown (defaults to their account name)
slug*	string
stars*	integer
comment	string
made_it	boolean	Set true only when the cook explicitly says they made it; omission preserves the review and does not finish a cook.
content_token	string
step_feedback	any

report_content

Flag a recipe, review, photo or a cook's profile for Befana's moderators: spam, offensive, unsafe as written, copied without permission, not a recipe, or something else. Use only when the cook asks ("report this review", "this recipe is dangerous"), in their words. Moderators review every report; nothing is hidden automatically.

Argument	Type	Description
id*	string	The recipe slug, the review id, the photo URL, or the cook's handle for a profile
kind*	string
note	string	What's wrong, in the cook's words
reason*	string	spam: Spam or advertising; offensive: Offensive or hateful; unsafe: Unsafe to cook or eat as written; copyright: Copied without permission; not_recipe: Not a real recipe; other: Something else

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "kind",
    "id",
    "reason"
  ],
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "The recipe slug, the review id, the photo URL, or the cook's handle for a profile"
    },
    "kind": {
      "enum": [
        "recipe",
        "review",
        "photo",
        "profile"
      ],
      "type": "string"
    },
    "note": {
      "type": "string",
      "maxLength": 500,
      "description": "What's wrong, in the cook's words"
    },
    "reason": {
      "enum": [
        "spam",
        "offensive",
        "unsafe",
        "copyright",
        "not_recipe",
        "other"
      ],
      "type": "string",
      "description": "spam: Spam or advertising; offensive: Offensive or hateful; unsafe: Unsafe to cook or eat as written; copyright: Copied without permission; not_recipe: Not a real recipe; other: Something else"
    }
  }
}

save_recipe

Keep a recipe in the cook's Saved list (My Kitchen on the website), or take it off with saved: false. Use when the cook says "save this", "keep that one", "add it to my favorites", or "take the chili off my saved". Saving twice is harmless. Returns the recipe link and where Saved lives.

Argument	Type	Description
slug*	string	Recipe slug from search_recipes
saved	boolean	false takes it off Saved (only when the cook asks)

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "description": "Recipe slug from search_recipes"
    },
    "saved": {
      "type": "boolean",
      "default": true,
      "description": "false takes it off Saved (only when the cook asks)"
    }
  }
}

search_recipes

Find recipes on Befana by keywords, ingredients, time or diet. Use when the cook asks "what's for dinner?", "something vegetarian under 30 minutes", "a good banana bread", "something with the spinach I have", or "show me my chili" (mine: true for their own, private ones included). The cook's allergies, diet and avoid list already apply, and their own recipes come first. Returns short summaries with slugs and urls; get_recipe has the full recipe. When the cook names a recipe search excluded, it comes back in hidden with why: don't stop to ask; go on with that slug, tell them why it was hidden before anything else, and never present it as safe. Works signed out (public recipes).

read-only

Argument	Type	Description
mine	boolean	Only the cook's own recipes and versions, including private ones
tags	array	All must match. In use: vegetarian, vegan, gluten-free, dairy-free, quick, dinner, breakfast, dessert, baking, soup, side, snack, make-ahead
limit	integer
query	string	Keywords, e.g. "lemon pasta" or "soup"
allergens	array	Explicit per-request allergen screening, separate from exclude_ingredients. Use at most nine entries: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame. Fixed aliases: dairy → milk, egg → eggs, peanut → peanuts, tree nuts → tree_nuts, soya → soy, sesame seeds → sesame. Nuts and seafood are ambiguous: specify tree_nuts/peanuts or fish/shellfish explicitly. Gluten is not wheat and lactose is not milk; neither is supported here. No spelling guesses are made. Retry with supported categories. Empty adds no restriction and never clears saved rules. Not saved to Befana preferences or plans.

suggest_from_pantry

Recipes ranked by how much the cook already has, each with what's missing ("You have 7 of 9. Missing: lemon, parmesan."). Use when the cook asks "what can I make?", "what can I do with chicken and rice?", or "the chicken has to get used tonight" (must_use). Uses their saved pantry; signed out, or for "what if I had…", pass pantry. Staples are assumed; allergies, diet and avoid list apply; keywords, tags and max_minutes narrow it. Read the top few with the have/missing line and the url; a list of just the missing items is the natural next step.

read-only

Argument	Type	Description
tags	array
limit	integer
query	string	Keywords, e.g. "soup"
pantry	array	Ingredient names to use instead of the saved pantry (signed out, or a what-if)
must_use	array	Ingredients the recipe has to use
max_minutes	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "limit": {
      "type": "integer",
      "default": 6,
      "maximum": 25,
      "minimum": 1
    },
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Keywords, e.g. \"soup\""
    },
    "pantry": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 300,
      "description": "Ingredient names to use instead of the saved pantry (signed out, or a what-if)"
    },
    "must_use": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 10,
      "description": "Ingredients the recipe has to use"
    },
    "max_minutes": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

update_meal_plan

Change the cook's saved meal plan in place: swap a day for another pick (constraints: faster, max_minutes, tags, query, or a slug the cook chose), drop a day, or add one, keeping their other days. Use when the cook says "swap Tuesday for something faster", "not the salmon", "we're out Thursday", "add one more dinner". Pass plan_id from plan_meals. Returns the whole plan by day, what changed, and the same list (same id and link), prep order, swaps, nutrition, cost and say, all recomputed. A dinner swapped out counts against it in later plans. Say what changed and the list line, then ask the one question in next_steps.

Argument	Type	Description
add	array	Meals to add: [{}] for one more dinner
drop	array	Days to take out of the plan: ["Thu"]
swap	array	Days to change: [{ day: "Tue", constraints: { faster: true } }]
units	string	US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting.
pantry	array
plan_id*	string	plan_id from plan_meals
with_shopping_list	boolean	Rebuild the plan's list in place (the default)

Input schema (JSON)

update_recipe

Change the cook's own recipe or version. Use when the cook says "add more garlic to my version", "make mine private", "take it down" (unpublished: true; off Befana for everyone but them, reversible; a recipe others have cooked or saved can only come down this way), "use my photo for the cover", "undo that last change", or "I made it tonight, took about 50 minutes" (tested; ask for the time if they didn't say, never assume). Pass only what changes; ingredients or steps, if passed, are the complete new list. photo: only one the cook took, never generated, stock or found; even when asked, name the recipe and get a yes first. Before calling, show the cook the changed ingredients and steps and get a yes; never save silently. Every edit keeps a revision (restore_revision: n undoes edit n). Not the cook's? Use fork_recipe. recover_photo is recovery-only: discover with get_my_kitchen section pending_photos, show the selected photo, target and current-cover replacement consequence, then wait for explicit selection and confirmation. cook_confirmed is the model's assertion, not independent proof of consent; never auto-confirm. Copy the full observed version unchanged and combine recovery with no other edits.

Argument	Type	Description
slug*	string	The cook's recipe or version to change
tags	array
photo	object	A photo the cook took of this dish: the cover, or a step with step. Pass image_url or image_base64. Never a generated, stock or found-online picture. Asking for it isn't the yes: first tell the cook which recipe and where ("I'll set this photo as the cover of <title>. OK?") and call only after they say yes. It goes through Befana's photo check (a cover needs daylight and at least 1200 px on the long side); a refusal says what to fix and nothing changes. It replaces the current cover, a placeholder illustration included. If you can't pass the file, the cook can use "Add a photo" on the recipe page. Change publication status (unpublished) in a separate call, never together with a photo.

update_shopping_list

Change a saved list after the cook answers what build_shopping_list or plan_meals set aside as likely_have, or says how the trip went. remove: things they have (they come off, and count as left off); need: set-aside things they're out of (they move to the buy aisles); add: anything else for the trip, as they said it; outcomes: what happened at the store per item (bought, skipped, bought_elsewhere with the store they name). Use when the cook says "I have the flour and oil", "I'm out of chili flakes" or "skipped the salmon, got the bread at the bakery". Changes only this list, never the pantry: ask "Want me to remember these for next time?" first, then call pantry. Returns the pared list, its estimate and the order offer.

Argument	Type	Description
add	array	Anything else for the same trip, amount included: ["paper towels", "2 lb bananas"]
need	array	Set-aside (likely_have) things the cook is out of: they go back to the buy list at full size
remove	array	Things the cook has, as they said them: ["flour", "olive oil"]
list_id*	string	Id of the saved list from build_shopping_list or plan_meals
outcomes	array	How the trip went, per line (#63): what they bought, skipped, or got somewhere else

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "list_id"
  ],
  "properties": {
    "add": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 50,
      "description": "Anything else for the same trip, amount included: [\"paper towels\", \"2 lb bananas\"]"
    },
    "need": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 100,
      "description": "Set-aside (likely_have) things the cook is out of: they go back to the buy list at full size"
    },
    "remove": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 80,
        "minLength": 1
      },
      "maxItems": 100,
      "description": "Things the cook has, as they said them: [\"flour\", \"olive oil\"]"
    },
    "list_id": {
      "type": "string",
      "description": "Id of the saved list from build_shopping_list or plan_meals"
    },
    "outcomes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "item",
          "outcome"
        ],
        "properties": {
          "item": {
            "type": "string",
            "maxLength": 80,
            "minLength": 1,
            "description": "The line, as the cook said it"
          },
          "store": {
            "type": "string",
            "maxLength": 60,
            "description": "With bought_elsewhere, only the store the cook named; never suggest one"
          },
          "outcome": {
            "anyOf": [
              {
                "enum": [
                  "bought",
                  "skipped",
                  "bought_elsewhere"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "bought, skipped or bought_elsewhere; null clears it"
          }
        }
      },
      "maxItems": 100,
      "description": "How the trip went, per line (#63): what they bought, skipped, or got somewhere else"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 30
      },
      "maxItems": 20
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "tip": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 140
              },
              {
                "type": "null"
              }
            ],
            "description": "A short pointer shown under the step, up to 140 characters: \"The batter should look lumpy; don't overmix.\""
          },
          "body": {
            "type": "string",
            "maxLength": 1000,
            "minLength": 1,
            "description": "Step text with amounts as tags: {flour}, a portion {butter:1/2}, oven temp in °F {t:375}"
          },
          "timer_minutes": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1440,
                "exclusiveMinimum": 0
              },
              {
                "type": "null"
              }
            ],
            "description": "Up to 24 hours (1440)"
          }
        }
      },
      "maxItems": 60,
      "minItems": 1
    },
    "title": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1
    },
    "author": {
      "type": "string",
      "maxLength": 80,
      "description": "Name to credit (the cook)"
    },
    "tested": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "minutes"
          ],
          "properties": {
            "minutes": {
              "type": "integer",
              "maximum": 2880,
              "minimum": 1,
              "description": "How long it took, start to finish, in minutes"
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Mark the recipe tested: the cook says they cooked it themselves and timed it. Ask the cook (\"Have you cooked this? About how long did it take, start to finish?\") and pass only what they say; never assume it, never estimate the minutes, and never mark a recipe tested because you drafted, imported or adapted it. null clears the mark. Shown as \"Tested by the cook · 45 min\" and counted as one timed cook."
    },
    "summary": {
      "type": "string",
      "maxLength": 400,
      "description": "One or two sentences on what makes it good"
    },
    "draft_id": {
      "type": "string",
      "maxLength": 64,
      "description": "A draft_id from draft_recipe, to publish that draft"
    },
    "servings": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0.25
    },
    "chef_note": {
      "type": "string",
      "maxLength": 500,
      "description": "The chef's note, up to 500 characters: a sentence or two in the cook's words on what makes the recipe theirs. Only what the cook said; never write one for them."
    },
    "visibility": {
      "enum": [
        "public",
        "private"
      ],
      "type": "string",
      "description": "private = just for the cook, from the first save (#171); public (the default) lists it under My recipes and in search"
    },
    "ingredients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "qty",
          "item"
        ],
        "properties": {
          "key": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-z0-9_-]+$",
                "maxLength": 24
              },
              {
                "type": "null"
              }
            ],
            "description": "Short tag steps use, e.g. \"flour\". When omitted: an ingredient already in the recipe keeps its key (match by item), a new one takes the tag your steps use for it if that tag is its name (\"nutritional_yeast\") or last word (\"yeast\"), else the last word of item."
          },
          "qty": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 100000,
                "minimum": 0
              },
              {
                "type": "string",
                "maxLength": 20
              }
            ],
            "description": "Amount, e.g. 1.5 or \"1 1/2\". Use 0 for 'to taste'."
          },
          "item": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1,
            "description": "Ingredient name, e.g. \"all-purpose flour\""
          },
          "note": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Prep note, e.g. \"finely chopped\""
          },
          "unit": {
            "type": "string",
            "default": "",
            "maxLength": 20,
            "description": "tsp, tbsp, cup, fl oz, qt, oz, lb, g, kg, ml, l, clove, can, slice, sprig, bunch, head, stick, each, or empty"
          }
        }
      },
      "maxItems": 80,
      "minItems": 1
    },
    "yield_label": {
      "type": "string",
      "maxLength": 40,
      "description": "servings, cookies, loaves, jars…"
    },
    "cook_minutes": {
      "type": "integer",
      "maximum": 2880,
      "minimum": 0
    },
    "prep_minutes": {
      "type": "integer",
      "maximum": 2880,
      "minimum": 0
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "description": "The original recipe's slug"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 30
      },
      "maxItems": 20
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "tip": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 140
              },
              {
                "type": "null"
              }
            ],
            "description": "A short pointer shown under the step, up to 140 characters: \"The batter should look lumpy; don't overmix.\""
          },
          "body": {
            "type": "string",
            "maxLength": 1000,
            "minLength": 1,
            "description": "Step text with amounts as tags: {flour}, a portion {butter:1/2}, oven temp in °F {t:375}"
          },
          "timer_minutes": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1440,
                "exclusiveMinimum": 0
              },
              {
                "type": "null"
              }
            ],
            "description": "Up to 24 hours (1440)"
          }
        }
      },
      "maxItems": 60,
      "minItems": 1
    },
    "title": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1
    },
    "author": {
      "type": "string",
      "maxLength": 80,
      "description": "Name to credit (the cook)"
    },
    "summary": {
      "type": "string",
      "maxLength": 400,
      "description": "One or two sentences on what makes it good"
    },
    "servings": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0.25
    },
    "chef_note": {
      "type": "string",
      "maxLength": 500,
      "description": "The chef's note, up to 500 characters: a sentence or two in the cook's words on what makes the recipe theirs. Only what the cook said; never write one for them."
    },
    "visibility": {
      "enum": [
        "public",
        "private"
      ],
      "type": "string",
      "description": "private = just for the cook; public (the default) lists it under the original"
    },
    "ingredients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "qty",
          "item"
        ],
        "properties": {
          "key": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-z0-9_-]+$",
                "maxLength": 24
              },
              {
                "type": "null"
              }
            ],
            "description": "Short tag steps use, e.g. \"flour\". When omitted: an ingredient already in the recipe keeps its key (match by item), a new one takes the tag your steps use for it if that tag is its name (\"nutritional_yeast\") or last word (\"yeast\"), else the last word of item."
          },
          "qty": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 100000,
                "minimum": 0
              },
              {
                "type": "string",
                "maxLength": 20
              }
            ],
            "description": "Amount, e.g. 1.5 or \"1 1/2\". Use 0 for 'to taste'."
          },
          "item": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1,
            "description": "Ingredient name, e.g. \"all-purpose flour\""
          },
          "note": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Prep note, e.g. \"finely chopped\""
          },
          "unit": {
            "type": "string",
            "default": "",
            "maxLength": 20,
            "description": "tsp, tbsp, cup, fl oz, qt, oz, lb, g, kg, ml, l, clove, can, slice, sprig, bunch, head, stick, each, or empty"
          }
        }
      },
      "maxItems": 80,
      "minItems": 1
    },
    "yield_label": {
      "type": "string",
      "maxLength": 40,
      "description": "servings, cookies, loaves, jars…"
    },
    "cook_minutes": {
      "type": "integer",
      "maximum": 2880,
      "minimum": 0
    },
    "prep_minutes": {
      "type": "integer",
      "maximum": 2880,
      "minimum": 0
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string"
    },
    "step": {
      "type": "integer",
      "maximum": 60,
      "minimum": 1,
      "description": "Just this step (1-based), for \"what's next?\" in a voice flow; the gather list comes only with step 1 or no step"
    },
    "units": {
      "enum": [
        "us",
        "metric"
      ],
      "type": "string",
      "description": "US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting."
    },
    "servings": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0.25
    },
    "allergens": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 9,
      "description": "Explicit per-request allergen screening, separate from exclude_ingredients. Use at most nine entries: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame. Fixed aliases: dairy → milk, egg → eggs, peanut → peanuts, tree nuts → tree_nuts, soya → soy, sesame seeds → sesame. Nuts and seafood are ambiguous: specify tree_nuts/peanuts or fish/shellfish explicitly. Gluten is not wheat and lactose is not milk; neither is supported here. No spelling guesses are made. Retry with supported categories. Empty adds no restriction and never clears saved rules. Not saved to Befana preferences or plans."
    },
    "from_step": {
      "type": "integer",
      "maximum": 60,
      "minimum": 1,
      "description": "This step and the rest, e.g. after a pause"
    },
    "units_for": {
      "type": "object",
      "description": "The cook's own unit for particular ingredients, by ingredient key or name: { \"butter\": \"tbsp\", \"flour\": \"g\" }. Units: tsp, tbsp, cup, fl oz, ml, oz, lb, g. When the cook asks for an amount in another unit, pass this rather than converting yourself; the ingredient list and every step follow. Ones that can't convert come back in ignored_units",
      "propertyNames": {
        "type": "string",
        "maxLength": 60
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 20
      }
    },
    "unknown_ingredients": {
      "enum": [
        "exclude",
        "flag"
      ],
      "type": "string",
      "description": "While allergen screening is active: exclude (default) omits insufficiently classified recipes; flag includes them with uncertainty. Named recipe retrieval always warns and returns the recipe."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "description": "Recipe slug from search_recipes"
    },
    "units": {
      "enum": [
        "us",
        "metric"
      ],
      "type": "string",
      "description": "US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting."
    },
    "servings": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0.25,
      "description": "Scale to this many servings (defaults to the cook's household size, then the recipe's own)"
    },
    "allergens": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 9,
      "description": "Explicit per-request allergen screening, separate from exclude_ingredients. Use at most nine entries: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame. Fixed aliases: dairy → milk, egg → eggs, peanut → peanuts, tree nuts → tree_nuts, soya → soy, sesame seeds → sesame. Nuts and seafood are ambiguous: specify tree_nuts/peanuts or fish/shellfish explicitly. Gluten is not wheat and lactose is not milk; neither is supported here. No spelling guesses are made. Retry with supported categories. Empty adds no restriction and never clears saved rules. Not saved to Befana preferences or plans."
    },
    "units_for": {
      "type": "object",
      "description": "The cook's own unit for particular ingredients, by ingredient key or name: { \"butter\": \"tbsp\", \"flour\": \"g\" }. Units: tsp, tbsp, cup, fl oz, ml, oz, lb, g. When the cook asks for an amount in another unit, pass this rather than converting yourself; the ingredient list and every step follow. Ones that can't convert come back in ignored_units",
      "propertyNames": {
        "type": "string",
        "maxLength": 60
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 20
      }
    },
    "substitute": {
      "type": "object",
      "properties": {
        "for": {
          "type": "string",
          "maxLength": 40,
          "description": "What the swap is for: a diet (vegetarian, vegan, pescatarian, gluten-free, dairy-free, low-sodium, halal, kosher), an allergen-free tag (egg-free, nut-free, peanut-free, sesame-free, shellfish-free, soy-free) or a context (baking, sauce, frying, dressing). Alone, it covers every ingredient that breaks that diet."
        },
        "ingredient": {
          "type": "string",
          "maxLength": 80,
          "description": "The ingredient to replace, e.g. \"butter\""
        }
      },
      "description": "Ask for substitutions: for one ingredient, for a diet, or both"
    },
    "unknown_ingredients": {
      "enum": [
        "exclude",
        "flag"
      ],
      "type": "string",
      "description": "While allergen screening is active: exclude (default) omits insufficiently classified recipes; flag includes them with uncertainty. Named recipe retrieval always warns and returns the recipe."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "zip": {
      "type": "string",
      "pattern": "^\\d{5}$",
      "description": "The cook's ZIP code, when they gave it; saved with their store. Never guess it"
    },
    "edits": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "line"
        ],
        "properties": {
          "line": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 500,
                "minimum": 1
              },
              {
                "type": "string",
                "maxLength": 60,
                "minLength": 1
              }
            ],
            "description": "The preview line's number or the item's name (\"hoisin sauce\")"
          },
          "remove": {
            "type": "boolean",
            "description": "true takes the line out of the cart"
          },
          "quantity": {
            "type": "integer",
            "maximum": 99,
            "minimum": 0,
            "description": "How many to add; 0 takes it out"
          }
        }
      },
      "maxItems": 50,
      "description": "The cook's changes to a preview (\"skip the hoisin\", \"2 salmon\"), with preview_id"
    },
    "store": {
      "type": "string",
      "maxLength": 60,
      "minLength": 1,
      "description": "The store the cook picked or named (\"Sprouts\", \"King Soopers\"), ideally one from choose_store. Saved as their store unless remember_store is false"
    },
    "units": {
      "enum": [
        "us",
        "metric"
      ],
      "type": "string",
      "description": "US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting."
    },
    "pantry": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ingredients the cook already has; they are not ordered"
    },
    "confirm": {
      "type": "boolean",
      "description": "true, with preview_id, once the cook said yes to the preview"
    },
    "list_id": {
      "type": "string",
      "description": "Id of a saved list from build_shopping_list or plan_meals"
    },
    "preview": {
      "type": "boolean",
      "description": "A cart grocer previews before adding anything (the default). false adds straight away, only when the cook said they don't need to check"
    },
    "recipes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "slug"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "servings": {
            "type": "number",
            "maximum": 1000,
            "minimum": 0.25
          }
        }
      },
      "maxItems": 21
    },
    "provider": {
      "type": "string",
      "maxLength": 40,
      "description": "Grocer to hand the list to: instacart, walmart, kroger, amazon or search. Omit for the cook's saved store, or Instacart when that store isn't available. An unknown or unavailable grocer returns an error listing the available ones."
    },
    "preview_id": {
      "type": "string",
      "maxLength": 40,
      "description": "A cart_preview's id: with edits it updates the preview, with confirm: true it adds exactly those items to the cart"
    },
    "remember_store": {
      "type": "boolean",
      "description": "false for a one-off order elsewhere; the saved store stays as it was"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "keep": {
      "type": "boolean",
      "description": "Older spelling of save: true = save, false = preview. Still works; prefer save"
    },
    "save": {
      "enum": [
        "save",
        "preview"
      ],
      "type": "string",
      "description": "\"preview\": show the plan and keep nothing (no id, no url, nothing in My Kitchen), signed in or out; use it when the cook says \"just show me\", \"don't save it yet\", \"an option\". \"save\": keep it in the cook's kitchen (signed out: the sign-in error). Left out: a signed-in call saves, a signed-out call previews. The receipt in the result says which happened"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Required tags, e.g. [\"vegetarian\"]"
    },
    "meals": {
      "type": "integer",
      "maximum": 14,
      "minimum": 1,
      "description": "How many meals to plan; leave out to use the cook's usual number (workflow.plan_meals in preferences), else 5"
    },
    "units": {
      "enum": [
        "us",
        "metric"
      ],
      "type": "string",
      "description": "US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting."
    },
    "pantry": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "occasion": {
      "enum": [
        "weeknight",
        "guests",
        "party"
      ],
      "type": "string",
      "default": "weeknight",
      "description": "weeknight: quick, everyday. guests or party: the plan comes with share links and an offer to adapt a recipe for a guest's needs before the list"
    },
    "servings": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0.25,
      "description": "Servings per meal (defaults to each recipe's own)"
    },
    "meal_type": {
      "enum": [
        "dinner",
        "breakfast",
        "any"
      ],
      "type": "string",
      "default": "dinner"
    },
    "max_budget": {
      "type": "number",
      "maximum": 10000,
      "description": "US dollars the plan's list should stay under (\"plan the week under $80\"): an estimate from national average prices, so say \"about\"",
      "exclusiveMinimum": 0
    },
    "guest_notes": {
      "type": "string",
      "maxLength": 200,
      "description": "Who's coming and what they need, in the cook's words: \"one vegetarian, Sam hates cilantro\". Used to offer a version of a recipe; never stored as a preference"
    },
    "max_minutes": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "min_protein": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Grams of protein per serving at least; defaults to the cook's saved target",
      "exclusiveMinimum": 0
    },
    "request_key": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "Your own id or receipt.request_key. First save wins for this cook and tool: within 10 minutes the same key returns the saved plan, even if arguments changed. New arguments need a new key; edits use update_*. Without a key Befana fingerprints arguments and applied preferences/pantry"
    },
    "max_calories": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Calories per serving at most for every meal; defaults to the cook's saved target",
      "exclusiveMinimum": 0
    },
    "with_shopping_list": {
      "type": "boolean",
      "default": true
    },
    "exclude_ingredients": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "avoid": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 40,
      "description": "Ingredients the cook dislikes"
    },
    "diets": {
      "type": "array",
      "items": {
        "enum": [
          "vegetarian",
          "vegan",
          "pescatarian",
          "gluten-free",
          "dairy-free",
          "low-sodium",
          "halal",
          "kosher"
        ],
        "type": "string"
      }
    },
    "skill": {
      "anyOf": [
        {
          "enum": [
            "beginner",
            "comfortable",
            "confident"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "store": {
      "type": "object",
      "required": [
        "retailer",
        "zip"
      ],
      "properties": {
        "zip": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{5}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "retailer": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "units": {
      "enum": [
        "us",
        "metric"
      ],
      "type": "string"
    },
    "pantry": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 100,
      "description": "Always-on-hand staples"
    },
    "servings": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 24,
          "minimum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Household size; null to use each recipe's own"
    },
    "workflow": {
      "type": "object",
      "properties": {
        "whats_new": {
          "enum": [
            "on",
            "off"
          ],
          "type": "string",
          "description": "off stops mentions of new Befana features"
        },
        "plan_meals": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 14,
              "minimum": 1
            },
            {
              "type": "null"
            }
          ],
          "description": "The cook's usual number of meals for plan_meals"
        },
        "offer_order": {
          "enum": [
            "always",
            "ask",
            "never"
          ],
          "type": "string",
          "description": "Grocery delivery after a list"
        },
        "setup_questions": {
          "enum": [
            "ask",
            "never"
          ],
          "type": "string",
          "description": "never stops questions like household size"
        },
        "offer_pantry_update": {
          "enum": [
            "always",
            "ask",
            "never"
          ],
          "type": "string",
          "description": "Adding an order to the pantry and taking a cooked recipe's ingredients off it"
        },
        "offer_shopping_list": {
          "enum": [
            "always",
            "ask",
            "never"
          ],
          "type": "string",
          "description": "Shopping list after a recipe or plan: always (the cook wants one every time), ask, never (stop offering)"
        },
        "offer_fork_on_substitution": {
          "enum": [
            "always",
            "ask",
            "never"
          ],
          "type": "string",
          "description": "Saving the cook's own version after a swap. always still shows the changes and needs their yes; it only skips asking to save"
        }
      },
      "description": "How the cook wants you to work with them. Pass only the keys that change"
    },
    "allergies": {
      "type": "array",
      "items": {
        "enum": [
          "milk",
          "eggs",
          "fish",
          "shellfish",
          "tree_nuts",
          "peanuts",
          "wheat",
          "soy",
          "sesame"
        ],
        "type": "string"
      },
      "description": "Major allergens: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame"
    },
    "equipment": {
      "type": "array",
      "items": {
        "enum": [
          "air fryer",
          "slow cooker",
          "instant pot",
          "no oven"
        ],
        "type": "string"
      }
    },
    "avoid_mode": {
      "enum": [
        "exclude",
        "rank_lower"
      ],
      "type": "string",
      "description": "exclude hides those recipes; rank_lower shows them lower"
    },
    "do_not_sell": {
      "type": "boolean",
      "description": "True keeps the cook out of every aggregated data product Befana sells or licenses"
    },
    "share_region": {
      "type": "boolean",
      "description": "False stops usage counts from recording the cook's state or country"
    },
    "cuisines_love": {
      "type": "array",
      "items": {
        "enum": [
          "American",
          "Chinese",
          "Indian",
          "Italian",
          "Japanese",
          "Korean",
          "Mediterranean",
          "Mexican",
          "Middle Eastern",
          "Thai"
        ],
        "type": "string"
      }
    },
    "cuisines_skip": {
      "type": "array",
      "items": {
        "enum": [
          "American",
          "Chinese",
          "Indian",
          "Italian",
          "Japanese",
          "Korean",
          "Mediterranean",
          "Mexican",
          "Middle Eastern",
          "Thai"
        ],
        "type": "string"
      }
    },
    "servings_mode": {
      "enum": [
        "offer",
        "always"
      ],
      "type": "string",
      "description": "offer (default): recipes open at their own servings and the household size is offered; always: recipes open scaled to it. Lists and meal plans use the household size either way"
    },
    "cook_confirmed": {
      "type": "boolean",
      "const": true,
      "description": "Required to change anything: true only when the cook asked for this exact change in their own words (non-health settings) or said yes after you restated it (always for allergies, diets, avoid list, privacy)"
    },
    "custom_allergies": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "maxItems": 40,
      "description": "Other allergy ingredients, e.g. [\"kiwi\"]"
    },
    "nutrition_targets": {
      "type": "object",
      "properties": {
        "min_protein": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 300,
              "minimum": 1
            },
            {
              "type": "null"
            }
          ],
          "description": "Grams of protein per serving at least; null clears it"
        },
        "max_calories": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 5000,
              "minimum": 50
            },
            {
              "type": "null"
            }
          ],
          "description": "Calories per serving at most; null clears it"
        }
      },
      "description": "Targets for one serving that plan_meals and search_recipes use by default (\"keep dinners under 600 calories\"). Not health data"
    },
    "weeknight_minutes": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 240,
          "minimum": 5
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "stars"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "Display name the cook wants shown (defaults to their account name)"
    },
    "slug": {
      "type": "string"
    },
    "stars": {
      "type": "integer",
      "maximum": 5,
      "minimum": 1
    },
    "comment": {
      "type": "string",
      "maxLength": 2000
    },
    "made_it": {
      "type": "boolean",
      "description": "Set true only when the cook explicitly says they made it; omission preserves the review and does not finish a cook."
    },
    "content_token": {
      "type": "string",
      "maxLength": 1024
    },
    "step_feedback": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "step",
              "issue"
            ],
            "properties": {
              "note": {
                "type": "string",
                "maxLength": 300
              },
              "step": {
                "type": "integer",
                "maximum": 100,
                "minimum": 1
              },
              "issue": {
                "enum": [
                  "timing",
                  "unclear",
                  "amount",
                  "other"
                ],
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "maxItems": 8
        },
        {
          "type": "null"
        }
      ]
    },
    "cook_session_id": {
      "type": "string",
      "description": "Session returned by get_cook_steps; identifies the cook being completed, validated against the signed-in cook and recipe."
    },
    "would_make_again": {
      "anyOf": [
        {
          "enum": [
            "yes",
            "no"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "substitutions_made": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1
          },
          "maxItems": 8
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "mine": {
      "type": "boolean",
      "default": false,
      "description": "Only the cook's own recipes and versions, including private ones"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "All must match. In use: vegetarian, vegan, gluten-free, dairy-free, quick, dinner, breakfast, dessert, baking, soup, side, snack, make-ahead"
    },
    "limit": {
      "type": "integer",
      "default": 8,
      "maximum": 25,
      "minimum": 1
    },
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Keywords, e.g. \"lemon pasta\" or \"soup\""
    },
    "allergens": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 9,
      "description": "Explicit per-request allergen screening, separate from exclude_ingredients. Use at most nine entries: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame. Fixed aliases: dairy → milk, egg → eggs, peanut → peanuts, tree nuts → tree_nuts, soya → soy, sesame seeds → sesame. Nuts and seafood are ambiguous: specify tree_nuts/peanuts or fish/shellfish explicitly. Gluten is not wheat and lactose is not milk; neither is supported here. No spelling guesses are made. Retry with supported categories. Empty adds no restriction and never clears saved rules. Not saved to Befana preferences or plans."
    },
    "from_pantry": {
      "type": "boolean",
      "default": false,
      "description": "Rank by what the cook has in their saved pantry (\"something with pasta from what I have\"); each result says what they have and what's missing. For a pure \"what can I make?\" use suggest_from_pantry"
    },
    "max_minutes": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Maximum prep + cook time as the author wrote it (total_minutes). The time range shown (time) is the author's estimate plus a quarter, or the crowd's range once enough cooks finished (time.basis says which), so it can run past the limit",
      "exclusiveMinimum": 0
    },
    "min_protein": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Grams of protein per serving at least (\"high protein\": 30). Defaults to the cook's saved target",
      "exclusiveMinimum": 0
    },
    "max_calories": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Calories per serving at most (\"under 500 calories\"). Defaults to the cook's saved target; recipes whose nutrition can't be fully counted are left out",
      "exclusiveMinimum": 0
    },
    "exclude_ingredients": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ingredient-name/canonical exclusions only, NOT allergen rules. Use allergens for explicit category screening; saved rules still apply"
    },
    "include_ingredients": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ingredients the recipe must use, e.g. what is in the fridge"
    },
    "unknown_ingredients": {
      "enum": [
        "exclude",
        "flag"
      ],
      "type": "string",
      "description": "While allergen screening is active: exclude (default) omits insufficiently classified recipes; flag includes them with uncertainty. Named recipe retrieval always warns and returns the recipe."
    }
  }
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "plan_id"
  ],
  "properties": {
    "add": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "day": {
            "type": "string",
            "maxLength": 24,
            "minLength": 1,
            "description": "A day the plan doesn't have yet (\"Sat\"); leave out for the next free day"
          },
          "slug": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "A recipe the cook chose; leave out to let Befana pick"
          },
          "constraints": {
            "type": "object",
            "properties": {
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 10,
                "description": "e.g. [\"vegetarian\"], [\"soup\"]"
              },
              "query": {
                "type": "string",
                "maxLength": 80,
                "description": "What the cook asked for, as search words: \"chicken\", \"tacos\""
              },
              "faster": {
                "type": "boolean",
                "description": "Quicker than the dinner it replaces (\"something faster\")"
              },
              "max_minutes": {
                "type": "integer",
                "maximum": 9007199254740991,
                "exclusiveMinimum": 0
              },
              "exclude_ingredients": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 20
              }
            },
            "description": "What the new dinner should be; leave out to let Befana pick against the rest of the week"
          }
        }
      },
      "maxItems": 7,
      "description": "Meals to add: [{}] for one more dinner"
    },
    "drop": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 24,
            "minLength": 1
          },
          {
            "type": "integer",
            "maximum": 14,
            "minimum": 1
          }
        ],
        "description": "A day as the plan shows it (\"Tue\", \"Tuesday\") or the meal's number"
      },
      "maxItems": 14,
      "description": "Days to take out of the plan: [\"Thu\"]"
    },
    "swap": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "day"
        ],
        "properties": {
          "day": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 24,
                "minLength": 1
              },
              {
                "type": "integer",
                "maximum": 14,
                "minimum": 1
              }
            ],
            "description": "A day as the plan shows it (\"Tue\", \"Tuesday\") or the meal's number"
          },
          "slug": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "A recipe the cook chose (from search_recipes); leave out to let Befana pick"
          },
          "constraints": {
            "type": "object",
            "properties": {
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 10,
                "description": "e.g. [\"vegetarian\"], [\"soup\"]"
              },
              "query": {
                "type": "string",
                "maxLength": 80,
                "description": "What the cook asked for, as search words: \"chicken\", \"tacos\""
              },
              "faster": {
                "type": "boolean",
                "description": "Quicker than the dinner it replaces (\"something faster\")"
              },
              "max_minutes": {
                "type": "integer",
                "maximum": 9007199254740991,
                "exclusiveMinimum": 0
              },
              "exclude_ingredients": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 20
              }
            },
            "description": "What the new dinner should be; leave out to let Befana pick against the rest of the week"
          }
        }
      },
      "maxItems": 14,
      "description": "Days to change: [{ day: \"Tue\", constraints: { faster: true } }]"
    },
    "units": {
      "enum": [
        "us",
        "metric"
      ],
      "type": "string",
      "description": "US cups/oz/°F or metric grams/ml/°C. Defaults to the cook's setting."
    },
    "pantry": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "plan_id": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "plan_id from plan_meals"
    },
    "with_shopping_list": {
      "type": "boolean",
      "default": true,
      "description": "Rebuild the plan's list in place (the default)"
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "description": "The cook's recipe or version to change"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 30
      },
      "maxItems": 20
    },
    "photo": {
      "type": "object",
      "properties": {
        "step": {
          "type": "integer",
          "maximum": 60,
          "description": "Put the photo on this step (1 is the first) instead of the cover",
          "exclusiveMinimum": 0
        },
        "image_url": {
          "type": "string",
          "maxLength": 2000,
          "description": "A public https link to the cook's photo (a share link, or the host's download link for a file the cook attached)"
        },
        "content_type": {
          "type": "string",
          "maxLength": 40,
          "description": "The file's type, e.g. image/jpeg; Befana reads it from the bytes"
        },
        "image_base64": {
          "type": "string",
          "maxLength": 4198400,
          "description": "The photo file itself as base64, for assistants that can read the cook's file: JPG, PNG, WebP or HEIC, up to 3 MB (bigger: pass image_url)"
        }
      },
      "description": "A photo the cook took of this dish: the cover, or a step with step. Pass image_url or image_base64. Never a generated, stock or found-online picture. Asking for it isn't the yes: first tell the cook which recipe and where (\"I'll set this photo as the cover of <title>. OK?\") and call only after they say yes. It goes through Befana's photo check (a cover needs daylight and at least 1200 px on the long side); a refusal says what to fix and nothing changes. It replaces the current cover, a placeholder illustration included. If you can't pass the file, the cook can use \"Add a photo\" on the recipe page. Change publication status (unpublished) in a separate call, never together with a photo."
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "tip": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 140
              },
              {
                "type": "null"
              }
            ],
            "description": "A short pointer shown under the step, up to 140 characters: \"The batter should look lumpy; don't overmix.\""
          },
          "body": {
            "type": "string",
            "maxLength": 1000,
            "minLength": 1,
            "description": "Step text with amounts as tags: {flour}, a portion {butter:1/2}, oven temp in °F {t:375}"
          },
          "timer_minutes": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 1440,
                "exclusiveMinimum": 0
              },
              {
                "type": "null"
              }
            ],
            "description": "Up to 24 hours (1440)"
          }
        }
      },
      "maxItems": 60,
      "minItems": 1
    },
    "title": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1
    },
    "author": {
      "type": "string",
      "maxLength": 80,
      "description": "Name to credit (the cook)"
    },
    "tested": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "minutes"
          ],
          "properties": {
            "minutes": {
              "type": "integer",
              "maximum": 2880,
              "minimum": 1,
              "description": "How long it took, start to finish, in minutes"
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Mark the recipe tested: the cook says they cooked it themselves and timed it. Ask the cook (\"Have you cooked this? About how long did it take, start to finish?\") and pass only what they say; never assume it, never estimate the minutes, and never mark a recipe tested because you drafted, imported or adapted it. null clears the mark. Shown as \"Tested by the cook · 45 min\" and counted as one timed cook."
    },
    "summary": {
      "type": "string",
      "maxLength": 400,
      "description": "One or two sentences on what makes it good"
    },
    "servings": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0.25
    },
    "chef_note": {
      "type": "string",
      "maxLength": 500,
      "description": "The chef's note, up to 500 characters: a sentence or two in the cook's words on what makes the recipe theirs. Only what the cook said; never write one for them."
    },
    "visibility": {
      "enum": [
        "public",
        "private"
      ],
      "type": "string"
    },
    "ingredients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "qty",
          "item"
        ],
        "properties": {
          "key": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-z0-9_-]+$",
                "maxLength": 24
              },
              {
                "type": "null"
              }
            ],
            "description": "Short tag steps use, e.g. \"flour\". When omitted: an ingredient already in the recipe keeps its key (match by item), a new one takes the tag your steps use for it if that tag is its name (\"nutritional_yeast\") or last word (\"yeast\"), else the last word of item."
          },
          "qty": {
            "anyOf": [
              {
                "type": "number",
                "maximum": 100000,
                "minimum": 0
              },
              {
                "type": "string",
                "maxLength": 20
              }
            ],
            "description": "Amount, e.g. 1.5 or \"1 1/2\". Use 0 for 'to taste'."
          },
          "item": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1,
            "description": "Ingredient name, e.g. \"all-purpose flour\""
          },
          "note": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200
              },
              {
                "type": "null"
              }
            ],
            "description": "Prep note, e.g. \"finely chopped\""
          },
          "unit": {
            "type": "string",
            "default": "",
            "maxLength": 20,
            "description": "tsp, tbsp, cup, fl oz, qt, oz, lb, g, kg, ml, l, clove, can, slice, sprig, bunch, head, stick, each, or empty"
          }
        }
      },
      "maxItems": 80,
      "minItems": 1
    },
    "show_counts": {
      "type": "boolean",
      "description": "Whether the page shows \"cooked N times · shared N times\" once there are enough cooks (#46); default on. false hides them"
    },
    "unpublished": {
      "type": "boolean",
      "description": "true takes the recipe off Befana for everyone but the cook (the link stays theirs, nothing is lost, their lists and plans still open it); false puts it back. Not an edit: no revision. Confirm first, like any change"
    },
    "yield_label": {
      "type": "string",
      "maxLength": 40,
      "description": "servings, cookies, loaves, jars…"
    },
    "cook_minutes": {
      "type": "integer",
      "maximum": 2880,
      "minimum": 0
    },
    "prep_minutes": {
      "type": "integer",
      "maximum": 2880,
      "minimum": 0
    },
    "recover_photo": {
      "type": "object",
      "required": [
        "photo_id",
        "expected_actor",
        "version",
        "cook_confirmed"
      ],
      "properties": {
        "version": {
          "type": "object",
          "required": [
            "id",
            "revision",
            "cover"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "maximum": 9007199254740991,
              "exclusiveMinimum": 0
            },
            "cover": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 2000
                },
                {
                  "type": "null"
                }
              ]
            },
            "revision": {
              "type": "integer",
              "maximum": 9007199254740991,
              "minimum": 0
            }
          },
          "description": "Exact observed version from pending_photos; copy every field unchanged, including cover (do not normalize its URL)",
          "additionalProperties": false
        },
        "photo_id": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1
        },
        "cook_confirmed": {
          "type": "boolean",
          "const": true,
          "description": "The assistant asserts the cook explicitly selected this photo and confirmed replacing this target's cover after seeing the preview and consequence. This flag is not independent proof of consent; never infer or auto-fill consent."
        },
        "expected_actor": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1,
          "description": "Copy from discovery; an account consistency check, never authorization"
        }
      },
      "description": "Recover an uploaded cover without another intake. Use only with slug; no other edits, uploads, restoration or publication. First discover with get_my_kitchen section pending_photos, show the selected preview, target and replacement consequence, and wait for the cook's explicit confirmation.",
      "additionalProperties": false
    },
    "attached_photo": {
      "type": "object",
      "required": [
        "download_url",
        "file_id"
      ],
      "properties": {
        "file_id": {
          "type": "string",
          "description": "The host's id for the file; the host fills this in"
        },
        "file_name": {
          "type": "string"
        },
        "mime_type": {
          "type": "string"
        },
        "download_url": {
          "type": "string",
          "description": "The host's temporary download link for the attached file; the host fills this in"
        }
      },
      "description": "A JPG, PNG or WebP photo the cook attached in the chat, for the cover (or a step with photo.step). Convert HEIC/HEIF to one of those formats first. Change publication status (unpublished) in a separate call, never together with a photo. ChatGPT fills in this file object when the cook attaches a picture; don't type a link here (a link goes in photo.image_url). The same rules as photo: only a photo the cook took of this dish; name the recipe and where it goes and get the cook's yes first; it goes through the photo check and replaces the current cover.",
      "additionalProperties": false
    },
    "restore_revision": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Undo: put the recipe back to how it was before edit n (see get_recipe's revisions). Other fields you pass apply on top.",
      "exclusiveMinimum": 0
    }
  }
}