Use Superwise with AI assistants

Tools

• save_recipe: Save a recipe in Superwise's format. Returns its id.
• search_recipes: Find recipes by title or ingredient, newest first.
• get_recipe: One recipe's ingredients and steps.
• import_recipe: Import a recipe page or social post with Superwise's importer. Uses the person's imports.
• get_import_status: How an import is going: queued, processing, saved, ready for review, or failed.
• add_recipe_photo: Give a recipe you saved its photo, from a public https address. Superwise keeps a copy.
• get_recipe_photo_upload_link: A one-time link to PUT the photo for a recipe you saved, as a file.
• get_week_plan: A week's planned meals, day by day, with any skipped days.
• plan_meal: Put a recipe on a day as breakfast, lunch or dinner. Adds; never replaces.
• get_shopping_list: A week's shopping list, by aisle, with what's ticked off.
• add_to_shopping_list: Add items to a week's list. Items already on it are reported, not added again.

Format

Superwise stores a recipe or list item exactly as it’s sent and does no clean-up, so it refuses anything that doesn’t match the schema, with an error naming the field. The full JSON Schema is in the tool listing.

• Every field in the schema is required; send null where it allows null. Unknown fields are refused.
• quantity is a number (0.5, not “1/2”), or null when the recipe gives no amount. Never estimate one.
• unit is one of g, kg, mg, ml, l, tsp, tbsp, cup, fl oz, oz, lb, pint, quart, gallon for measures, or a singular count word: clove, can, tin, jar, bottle, packet, bag, box, block, carton, slice, piece, fillet, rasher, stick, sheet, head, bulb, stalk, sprig, leaf, bunch, handful, pinch, dash, drop, splash, knob, scoop, ball, cube, loaf, ear, link, wedge. null for a plain count (“2 eggs”) or no amount.
• category is one of Produce, Meat & Seafood, Dairy & Eggs, Bakery, Pantry, Spices & Condiments, Frozen, Drinks, Other.
• Text is plain: no markup, no line breaks except within a step, and no hidden or control characters.
• source_url is the https page the recipe came from, or null for a recipe the person or assistant made.
• save_recipe requires a new UUID as request_id for each recipe, and the same one on every retry. It cannot be null.
• import_recipe takes an http or https link and a request_id (a UUID, the same on a retry). It runs in the background; follow it with get_import_status.
• Dates are YYYY-MM-DD. week_of is any day in the week, or null for this week; weeks start on the day the person's space is set to.
• plan_meal needs a slot (breakfast, lunch or dinner); Superwise doesn't pick one. Dates run from yesterday to a year ahead, with at most 6 meals on a day.
• A photo is for a recipe you saved through the same connection that has none yet: JPEG, PNG or WebP, under 8 MB, 200 to 4096 pixels a side. It's stored as a JPEG without metadata. Addresses must be public https; an upload link works for one PUT within 15 minutes.
• A list item has name, quantity, unit and category, with the same units and categories as an ingredient. Up to 50 items a call, and 300 on a list.

Without a connection: the save link

An assistant with no connection can hand the person a save link instead. It opens Superwise with the recipe filled in for them to check, and nothing is saved until they press Save.

• The link is /save#recipe= followed by the recipe as UTF-8 JSON, base64url-encoded (RFC 4648 section 5: - and _ instead of + and /, padding optional).
• The JSON uses save_recipe's fields and recipe validation: title, servings, total_time_minutes, ingredients (each: name, quantity, unit, category, part, note), steps, tags, source_url, request_id, every one present. Unlike the MCP tool, a save link allows request_id to be null because the person checks and saves it.
• The recipe goes after the #, so it never reaches a server. It carries no photo, and a recipe saved from it isn't marked as saved by an assistant: the person saved it.
• At most 32,000 characters after recipe=. A link that doesn't match shows the person what's wrong, naming the field.

https://superwise.recipes/save#recipe=eyJ0aXRsZSI6IkNoZWVzZSBvbiB0b2FzdCIsInNlcnZpbmdzIjoxLCJ0b3RhbF90aW1lX21pbnV0ZXMiOjEwLCJpbmdyZWRpZW50cyI6W3sibmFtZSI6ImJyZWFkIiwicXVhbnRpdHkiOjEsInVuaXQiOiJzbGljZSIsImNhdGVnb3J5IjoiQmFrZXJ5IiwicGFydCI6bnVsbCwibm90ZSI6bnVsbH0seyJuYW1lIjoiY2hlZGRhciIsInF1YW50aXR5Ijo0MCwidW5pdCI6ImciLCJjYXRlZ29yeSI6IkRhaXJ5ICYgRWdncyIsInBhcnQiOm51bGwsIm5vdGUiOiJncmF0ZWQifV0sInN0ZXBzIjpbIlRvYXN0IHRoZSBicmVhZCBvbiBvbmUgc2lkZS4iLCJUdXJuIGl0IG92ZXIsIHRvcCB3aXRoIHRoZSBjaGVlc2UgYW5kIGdyaWxsIHVudGlsIGJ1YmJsaW5nLiJdLCJ0YWdzIjpbXSwic291cmNlX3VybCI6bnVsbCwicmVxdWVzdF9pZCI6bnVsbH0 is a worked example; the full format and its JSON are in llms.txt.